Payments

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

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:

Payment Status

The steps in the payment lifecycle may be reported as follows:

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:

• Pay In Status Notification
• Get Pay In Details endpoint

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"
       }
   }
}