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.
Payment Schemes Supported
The below 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 |
Please note, that where 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
Several types of payment may be conducted 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 two of your account |
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 may be reported as follows:
Status | Description |
---|---|
PROCESSING | Processing of the payment 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 could not be completed |
Receiving 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 may represent, for example:
- A payment you have collected from your customers through Yapily Payments or Yapily Bulk 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, its account identifiers (e.g. Sort Code and Account number for GBP accounts, or IBAN for a EUR account) must be used. You can access these by getting your account information.
Making a Yapily Payment or Bulk Payment into a Virtual Account
You can collect payments that you instruct through Yapily Payments or Yapily Bulk Payments into your virtual account and therefore receive a settlement notification once funds have arrived.
To do so, initiate the payment in the usual way, specifying your virtual account and its associated accountIdentifications
within the payee
object.
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 or Yapily Bulk Payment that was previously initiated.
Where this is identified, the pay in status notification that you receive will contain an additional reconciledPaymentInitiationId
property that contains the id
of the payment you initiated.
Accessing source account details
For most pay ins that are received, you will have access to the source / sender account details. These are accounts that you may wish to make a pay out to, such as to cater for customer refunds or withdrawals.
The source account details can be found in the source object
contained within the following interfaces:
Making 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, which may include:
- Final settlement to your business account
- Settlement to one of your clients (e.g. a merchant)
- A refund to a customer
- A customer withdrawal / pay out from your app
Setting 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.
Instructing 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. This chosen scheme will need to have been added as one supported by the beneficiary during its creation.
A unique value must be supplied in the idempotency-key
header in order to achieve idempotency. If two requests are submitted with the same value, the second request will not be processed.
Request:
curl --location --request POST 'https://api.yapily.com/virtual-accounts/payments/pay-outs' \
--header 'Content-Type: application/json' \
--header 'client-id: <virtual_account_client_id>' \
--header 'idempotency-key: <idempotency_key>' \
--header 'Authorization: Bearer <access_token>' \
--data-raw '{
"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
{
"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 may retrieve the current status using the Get Payment endpoint.
Transferring funds between accounts
You can move funds between two 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 two requests are submitted with the same value, the second request will not be processed.
Request:
curl --location --request POST 'https://api.yapily.com/virtual-accounts/payments/transfers' \
--header 'Content-Type: application/json' \
--header 'client-id: <virtual_account_client_id>' \
--header 'idempotency-id: <idempotency_key>'\
--header 'Authorization: Bearer <access_token>' \
--data-raw '{
"source": {
"accountId": "04006d46-776d-4f9a-ae11-a4c9ab0aee3c"
},
"destination": {
"accountId": "78f1fbe0-f831-4f92-a4d0-5b0747103f9d"
},
"amount": {
"amount": 1,
"currency": "GBP"
},
"reference": "Transfer - 1"
}'
A successful response will appear as below:
{
"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"
}
}
}
Retrieving a list of payments
You can retrieve a list of the payments that have been made into and out of your virtual accounts using the Get Payments endpoint providing any of the available query parameters to filter the list as required.
Request:
curl --location --request GET 'https://api.yapily.com/virtual-accounts/payments' \
--header 'client-id: <virtual_account_client_id>' \
--header 'Authorization: Bearer <access_token>'
A successful response will appear as below:
{
"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"
}
}
]
}
Getting payment details
You can retrieve information about a specific payment by using the Get Payment endpoint. You need to specify the id
of the payment you wish to retrieve in the path.
Request:
curl --location --request GET 'https://api.yapily.com/virtual-accounts/payments/{payment-id}\
--header 'client-id: <virtual_account_client_id>' \
--header 'Authorization: Bearer <access_token>'
A successful response will appear as below::
{
"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"
}
}
}