Payments
Virtual Accounts feature is available as a Private Beta version. Please contact your Customer Success Manager if you would like to access it.
You can receive funds into your account (make a Pay In), send funds to an external account (make a Pay Out) and transfer funds between accounts.
Supported payment schemes
The following table outlines each of the supported payment schemes for Pay In and Pay Out and their key characteristics:
Currency | Payment Scheme | Beneficiary Countries | Payment Limit | Cut-off | Estimated Settlement Time |
---|---|---|---|---|---|
GBP | Faster Payments | GB | GBP 1,000,000 | - | Instant 24/7/365 |
GBP | CHAPS | GB | - | 5:30 PM GMT for same day Next business day after cut-off |
1 - 2 hours (business days only) |
GBP | SWIFT | All except sanctioned countries | - | 3:00 PM GMT for same day | 2-5 working days depending on the destination country |
GBP | SWIFT Express | All except sanctioned countries | - | 2:00 PM GMT | 1 working day |
EUR | SEPA | All SEPA Countries | - | 2:00 PM GMT for same day. Next business day after cut-off. |
2 - 3 hours (business days only) |
EUR | SEPA Instant | All SEPA Countries | EUR 100,000 | - | Instant 24/7/365 |
EUR | SWIFT | All except sanctioned countries | - | 3:00 PM GMT for same day | 2-5 working days depending on the destination country |
EUR | SWIFT Express | All except sanctioned countries | - | 2:00 PM GMT | 1 working day |
USD | IAT | US | - | 6:00 PM GMT | Next working day |
USD | WIRE | US | - | 6:00 PM GMT | Next working day |
CAD | SWIFT | All except sanctioned countries | - | 3:00 PM GMT for same day | 2-5 working days depending on the destination country |
CZK | SWIFT | All except sanctioned countries | - | 3:00 PM GMT for same day | 2-5 working days depending on the destination country |
HUF | SWIFT | All except sanctioned countries | - | 3:00 PM GMT for same day | 2-5 working days depending on the destination country |
HUF | SWIFT Express | All except sanctioned countries | - | 12:30 PM GMT | 1 working day |
RON | SWIFT | All except sanctioned countries | - | 3:00 PM GMT for same day | 2-5 working days depending on the destination country |
HRK | SWIFT | All except sanctioned countries | - | 3:00 PM GMT for same day | 2-5 working days depending on the destination country |
info
If a payment is instructed via SEPA_INSTANT
, but the destination bank does not support this, the payment will instead be sent via SEPA_CREDIT
.
Payment types
You can conduct the following types of payment on your account:
Type | Description |
---|---|
PAY_IN | Funds received into your account |
PAY_OUT | Funds sent from your account to an external bank account |
TRANSFER | Funds transferred between 2 of your accounts |
RETURN_IN | The return of a pay out due to it being rejected by the beneficiary bank |
RETURN_OUT | The return of a pay in due to it being recalled by the sending bank |
Payment status
The steps in the payment lifecycle are reported as follows:
Status | Description |
---|---|
PROCESSING | Processing of a payment that is still in progress. |
COMPLETED | The payment has been successfully processed. Funds will have been credited to or debited from your account, dependent on the payment type. For a Pay Out, the instruction has been released to the payment scheme and settlement at the beneficiary is expected according to the estimated settlement periods. |
FAILED | The payment couldn't be completed. |
Receive payments into a Virtual Account (Pay In)
Funds that are received into your virtual account from an external source are known as a Pay In.
A Pay In can represent:
- A payment you have collected from your customers through Yapily Payments
- A payment you have collected from your customers through any payment method that utilises the supported payment schemes (e.g. a bank transfer over FPS to a GBP account)
- Payments that you have requested your PSP to settle into your virtual account
- Funds you have deposited to your account through any payment method that utilises the supported payment schemes
To instruct payment into your account, specify your virtual account as the payee in the payment request body using the account identification type VIRTUAL_ACCOUNT_ID
, and the account ID of your virtual account as the identification. You can retrieve your account ID by getting your account information.
Make a Yapily Payment into a Virtual Account
You can collect payments that you instruct through Yapily Payments into your virtual account and therefore receive a settlement notification once funds have arrived.
Initiate the payment, specifying an account identification type of VIRTUAL_ACCOUNT_ID
within the accountIdentifications
block, inside the payee
object.
Example Request:
{
"userUuid": "30a556b4-b5f7-4dc9-a226-3f562a6ecfe3",
"institutionId": "mock-sandbox",
"paymentRequest": {
"type": "DOMESTIC_PAYMENT",
"paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
"reference": "REFERENCE",
"contextType": "OTHER",
"amount": {
"amount": "1.00",
"currency": "GBP"
},
"payee": {
"accountIdentifications": [
{
"type": "VIRTUAL_ACCOUNT_ID",
"identification": "{{account-id}}"
}
]
}
}
}
To ensure that the payments you initiate can be reconciled to the Pay Ins on your account, the reference
must be unique for each payment. We also recommend it is a maximum of 18 characters.
A COMPLETED
payment status indicates that the payer bank has initiated the payment and that funds should settle into your virtual account in due course.
When settlement does occur it will result in a Pay In on the virtual account. You can be notified of when this occurs by subscribing to virtualAccount.payIn.status
notifications.
Reconciling Yapily Payments to Pay Ins
When a Pay In is received on your account, it will be identified whether it relates to a Yapily Payment that was previously initiated.
Where this is identified, the Pay In Status notification that you receive will contain an additional paymentInitiationId
property that contains the id
of the payment you initiated.
Access source account details
For most Pay Ins that are received, you will have access to the source or sender's account details. These are accounts that you may wish to make a Pay Out to, for example, for customer refunds or withdrawals.
The source account details can be found in the source object
contained in the following interfaces:
Make a payment to an external bank account (Pay Out)
You can make a payment from your virtual account, to any account that is connected to the supported payment schemes.
This payment could be for any purpose, for example:
- Final settlement to your business account
- Settlement to one of your clients (e.g. a merchant)
- A refund to a customer
- A customer withdrawal or pay out from your app
Set up a beneficiary
To send money to an account, it must be set up as a beneficiary.
If the beneficiary already exists then you can verify its details, if required, using the Get Beneficiary endpoint.
If the beneficiary does not yet exist, it must be added using the Create Beneficiary endpoint.
Instruct the Pay Out
Once the beneficiary is in place you can instruct a payment to it using the Create Pay Out endpoint.
As part of this request, you need to specify the paymentScheme
you want to use. The chosen scheme will need to have been added as supported by the beneficiary during its creation.
A unique value must be supplied in the idempotency-key
header in order to achieve idempotency. If 2 requests are submitted with the same value, the second request will not be processed.
Example request:
curl -L -X POST 'https://api.yapily.com/virtual-accounts/payments/pay-outs' \
-H 'Content-Type: application/json' \
-H 'client-id: <virtual_account_client_id>' \
-H 'idempotency-key: <idempotency_key>' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
"accountId": "<account-id>",
"amount": {
"amount": 10,
"currency": "GBP"
},
"reference": "REFERENCE",
"beneficiaryId": "<beneficiary-id>",
"paymentScheme": "FASTER_PAYMENTS"
}'
Upon successful creation, you will be provided with an id
for the Pay Out and it will have a status of INITIATED
.
Example response:
{
"meta": {
"tracingId": "0c62dfa1678442f2955707515ff67f49"
},
"data": {
"id": "6172f457-a667-40cc-be97-cd9f0e42b6af",
"createdDate": "2022-05-16T20:55:02.692Z",
"paymentDate": "2022-05-16",
"type": "PAY_OUT",
"paymentScheme": "FASTER_PAYMENTS",
"amount": {
"amount": -1,
"currency": "GBP"
},
"reference": "REFERENCE",
"status": "INITIATED",
"source": {
"type": "ACCOUNT",
"accountId": "a1JUMS93c1JQTnBSOHdzdmtITFBaQT09"
},
"destination": {
"type": "BENEFICIARY",
"beneficiaryId": "45c4f822-e12c-4800-8227-d7eb6ac2b0b7"
}
}
}
The payment will then be executed. To understand when the payment is COMPLETED
or FAILED
we recommend subscribing to virtualAccount.payOut.status
events.
Alternatively, you can retrieve the current status of the payment using the Get Payment endpoint.
Transfer funds between accounts
You can move funds between 2 of your accounts of the same currency using the Create Transfer endpoint.
A unique value must be supplied in the idempotency-key
header in order to achieve idempotency. If 2 requests are submitted with the same value, the second request will not be processed.
Example request:
curl -L -X POST 'https://api.yapily.com/virtual-accounts/payments/transfers' \
-H 'Content-Type: application/json' \
-H 'client-id: <virtual_account_client_id>' \
-H 'idempotency-id: <idempotency_key>'\
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
"source": {
"accountId": "04006d46-776d-4f9a-ae11-a4c9ab0aee3c"
},
"destination": {
"accountId": "78f1fbe0-f831-4f92-a4d0-5b0747103f9d"
},
"amount": {
"amount": 1,
"currency": "GBP"
},
"reference": "Transfer - 1"
}'
Example response:
{
"meta": {
"tracingId": "ae00b32635894d83a21bc24c5bbd4d41"
},
"data": {
"id": "604038fb-1205-4594-8893-0b83540e7174",
"createdDate": "2022-05-23T14:43:39.579Z",
"type": "TRANSFER",
"amount": {
"amount": -1,
"currency": "GBP"
},
"reference": "REF 123456",
"status": "INITIATED",
"source": {
"type": "ACCOUNT",
"accountId": "VnJhVy9NclFEbmdQREZCUWVIYWlRZz09"
},
"destination": {
"type": "ACCOUNT",
"accountId": "dk96dzJpUW9KOGlYMDRhVG14Q2NhUT09"
}
}
}
Retrieve list of payments
You can retrieve a list of payments that have been made into and out of your virtual accounts using the Get Payments endpoint. You can provide query parameters to filter the list as required.
Example request:
curl -L -X GET 'https://api.yapily.com/virtual-accounts/payments' \
-H 'client-id: <virtual_account_client_id>' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'
Example response:
{
"meta": {
"tracingId": "4c29beddb2f7431aa59946b3f00df711"
},
"links": {
"next": "https://api.yapily.com/virtual-accounts/payment?type=TRANSFER&cursor=cGFnZT0xJnNpemU9MTAwMA==",
"self": "https://api.yapily.com/virtual-accounts/payment?type=TRANSFER&cursor=cGFnZT0wJnNpemU9MTAwMA==",
"first": "https://api.yapily.com/virtual-accounts/payment?type=TRANSFER&cursor=cGFnZT0wJnNpemU9MTAwMA=="
},
"data": [
{
"id": "cb5c0f24-d70f-4614-9641-4f54e4035d5f",
"createdDate": "2022-06-10T12:47:01.55Z",
"type": "TRANSFER",
"amount": {
"amount": -1.0,
"currency": "GBP"
},
"reference": "ref-1",
"status": "COMPLETED",
"source": {
"type": "ACCOUNT",
"accountId": "ea1232ff-3fe7-4d51-abbe-5fb8d308fd15"
},
"destination": {
"type": "ACCOUNT",
"accountId": "00961c0d-5bb9-40d7-9cbe-6a47876556d0"
}
},
{
"id": "6f340fc7-60cb-43a1-aca6-c78919fe6126",
"createdDate": "2022-06-13T08:24:49.861Z",
"type": "TRANSFER",
"amount": {
"amount": -0.01,
"currency": "GBP"
},
"reference": "REF 123456",
"status": "COMPLETED",
"source": {
"type": "ACCOUNT",
"accountId": "ea1232ff-3fe7-4d51-abbe-5fb8d308fd15"
},
"destination": {
"type": "ACCOUNT",
"accountId": "00961c0d-5bb9-40d7-9cbe-6a47876556d0"
}
}
]
}
Get payment details
You can retrieve information about a specific payment using the Get Payment endpoint. You need to specify the id
of the payment you wish to retrieve in the path.
Example request:
curl -L -X GET 'https://api.yapily.com/virtual-accounts/payments/{payment-id}' \
-H 'client-id: <virtual_account_client_id>' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'
Example response:
{
"meta": {
"tracingId": "497a9d43c043411eb266539101324703"
},
"data": {
"id": "2f2cdeb8-4438-43db-955e-59ecac68a3bb",
"createdDate": "2022-05-23T15:24:48.873Z",
"paymentDate": "2022-05-23",
"type": "PAY_OUT",
"paymentScheme": "FASTER_PAYMENTS",
"amount": {
"amount": -1.0,
"currency": "GBP"
},
"reference": "Payment from John",
"status": "RELEASED",
"source": {
"type": "ACCOUNT",
"accountId": "5dd9a19f-c89a-4c93-a65e-617e3c4f83ef"
},
"destination": {
"type": "BENEFICIARY",
"beneficiaryId": "d919d0f8-7ec6-44a2-ae50-024f7d516f4e"
}
}
}