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.

Virtual Account Pay In flow

Initiate the payment, specifying an account identification type of VIRTUAL_ACCOUNT_ID within the accountIdentifications block, inside the payee object.

Example Request:

Copy

Copied

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

Virtual Account Pay In flow

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:

Copy

Copied

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:

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

Copy

Copied

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:

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

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:

Copy

Copied

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:

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

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:

Copy

Copied

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:

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