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.

Virtual Account Pay In flow

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

Virtual Account Pay In flow

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:

Copy
Copied
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

Copy
Copied
{
   "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:

Copy
Copied
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:

Copy
Copied
{
   "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:

Copy
Copied
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:

Copy
Copied
{
   "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:

Copy
Copied
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::

Copy
Copied
{
   "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"
       }
   }
}