Payments

Virtual Accounts feature is available as a Private Beta version. Please contact your Customer Success Manager if you would like to access it.

Introduction

The following payment types are supported on your virtual account:

Type	Description
PAY_IN	Funds received into your account
PAY_OUT	Funds sent from your account to an external bank account
REFUND	Refund a payment back to the original payer
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

Pay In & Pay Out

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

By collecting payments that you instruct through Yapily Payments into your virtual account, you are guaranteed to receive a settlement notification once the funds have arrived.

Virtual Account Pay In flow

Create a Pay In

Initiate the payment, specifying your virtual account inside the payee object.

In the accountIdentifications block, specify the type as VIRTUAL_ACCOUNT_ID, and the identification as your virtual account ID.

You can retrieve your account ID by getting your account information.

To ensure that the payments you initiate can be linked 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.

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

A COMPLETED payment status indicates that the payer bank has initiated the payment and it has been successfully processed. When the funds settle, this results in a Pay In to your virtual account

Subscribe to virtualAccount.payIn.status notifications to be notified of changes in the payment status.

Reconciling Yapily Payments to Pay Ins

When a Pay In is received on your account, we confirm whether it relates to a previously initiated Yapily Payment.

If so, the Pay In status notification will contain an additional field, paymentInitiationId, with the corresponding Yapily Payment ID.

Access source account details

The source account or sender's account details can be found in the source object in the following responses:

Pay Out

You can make a payment from your virtual account to any account that is connected via the supported payment schemes.

This payment can be for any purpose, for example:

Final settlement to your business account
Settlement to one of your clients (e.g. a merchant)
A customer withdrawal or pay out from your app

Virtual Account Pay Out flow

Create a Pay Out

1. Set up a beneficiary

To send money to an account, it must be set up as a beneficiary.

If the beneficiary already exists, you can verify its details using the Get Beneficiary endpoint.

If the beneficiary doesn't exist, it must be created using the Create Beneficiary endpoint.

2. Execute the request

Once the beneficiary exists, you can instruct a payment to it using the Create Pay Out endpoint.

You need to include the paymentScheme in the request. The paymentScheme must be supported by the beneficiary as specified when creating the beneficiary.

A unique value must be supplied in the idempotency-key header. 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"
}'

If created successfully, 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 is then executed.

Subscribe to virtualAccount.payOut.status notifications to be notified of changes in the payment status.

Alternatively, you can check the current status of the payment by retrieving the payment details.

Returns

Pay Out Return

A return may be sent by the beneficiary bank when they initially accept a payment request but, subsequently, cannot credit the funds to the beneficiary. Reasons for this occurring may include compliance checks at the beneficiary bank or an invalid beneficiary account status.

This return of funds is seen as a separate credit payment of type RETURN_IN. This is linked to the original (pay out) payment through the originalPaymentId

Because the payment request was initially accepted by the beneficiary bank, it is likely that the Pay Out is of COMPLETED status at the time the return is made. Typically, returns will occur within the normal settlement period of the payment scheme.

Subscribe to Pay Out return notifications to be notified when one of your Pay Outs is returned.

Pay In Return

In the event of a payer/sender wishing to recall a payment they have sent you, we will contact you in order to agree the correct action to take. If the recall is actioned, then a RETURN_OUT payment will be made. This is linked to the original (pay in) payment through the originalPaymentId

Retrieve payments

Get a list of payments

You can retrieve a list of payments made into and out of your virtual account 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 and the status of a specific payment using the Get Payment endpoint. You must provide the id of the payment you want 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": "COMPLETED",
    "source": {
      "type": "ACCOUNT",
      "accountId": "5dd9a19f-c89a-4c93-a65e-617e3c4f83ef"
    },
    "destination": {
      "type": "BENEFICIARY",
      "beneficiaryId": "d919d0f8-7ec6-44a2-ae50-024f7d516f4e"
    }
  }
}

Payment status

The steps in the payment lifecycle are:

Status	Description
INITIATED	Payment validated and accepted for processing.
PROCESSING	Payment processing.
SCHEDULED	Payment validated and scheduled for execution on the requested future date.
COMPLETED	Payment 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	Payment failed.

Subscribe to virtualAccount.payIn.status and virtualAccount.payOut.status notifications to be notified of changes in payment status.

Supported payment schemes

Table of the supported payment schemes for Pay In and Pay Out

Currency	Payment Scheme	Beneficiary Countries	Payment Limit	Cut-off	Estimated Settlement Time
GBP	Faster Payments	GB	GBP 1,000,000	-	Instant 24/7/365
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

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.

For type Pay In when currency is GBP, SWIFT payment scheme is supported.

Payment data validation

Payment reference

The validation of a payment reference depends on the target paymentScheme :

Payment Scheme(s)	Min Length	Max Length	Allowed Characters	Other
FASTER_PAYMENTS	1	18	Alpha (a-z, A-Z) Numeric (0-9) (space) , (comma) . (fullstop) - (hyphen)
SEPA_INSTANT SEPA_CREDIT	2	140	Alpha (a-z, A-Z) Numeric (0-9) + (plus) - (hyphen) / (forward slash) ? (question mark) . (fullstop) : (colon) , (comma) ( (open bracket) ) (close bracket) (space)	Cannot consist of a single repeated character e.g. aaa

Refunds

note

Only Yapily Open Banking Payments can be refunded.
Refunds can only be issued back to the source or original payer.

You can refund a payment made to your virtual account back to the source or original payer.

Refunds are sent through SEPA Instant (EUR) or Faster Payments (GBP).

You can optionally make a partial refund, or specify the execution date.

Virtual Account Refund flow

Create a refund

Make a request to the create refund endpoint, specifying the ID of the original Yapily Payment as the paymentInitiationId.

note

The payment must have settled in the virtual account to request a refund.

Example request:

Copy

Copied

curl -L -X POST 'https://api.yapily.com/virtual-accounts/refunds' \
-H 'Content-Type: application/json' \
-H 'client-id: <virtual_account_client_id>' \
-H 'idempotency-id: <idempotency_key>'\
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
    "originalPayment": { 
        "paymentInitiationId": "<ORIGINAL_PAYMENT_ID>"
    },
    "reason": "REQUESTED_BY_CUSTOMER",
    "reference": "Refund 123", 
    "refundTo": "SOURCE",
    "beneficiaryType": "INDIVIDUAL"  
}'

Create a partial refund

By default the refund amount is equal to the amount of the original payment.

To create a partial refund include the amount object in the request body:

Copy

Copied

...
"amount": {
    "amount": 10,
    "currency": "GBP"
    }
...

Create a future refund

By default the paymentDate is the same date you make the request.

To execute the refund in the future, include the paymentDate field in the request body specifying the date you want the refund to occur:

Copy

Copied

...
"paymentDate": "2025-08-28"
...

Example response:

Copy

Copied

{
  "data": {
    "id": "46d3349e-6733-459d-a6da-71850a7e8076",
    "originalPayment": {
      "paymentInitiationId": "<ORIGINAL_PAYMENT_ID>"
    },
    "status": "INITIATED",
    "amount": {
      "amount": 10,
      "currency": "GBP"
    },
    "reason": "REQUESTED_BY_CUSTOMER",
    "paymentDate": "2022-08-28",
    "reference": "Refund 123",
    "beneficiaryType": "INDIVIDUAL",
    "createdDateTime": "2022-04-31T15:00:57.345Z",
    "updatedDateTime": "2022-05-31T14:00:57.751Z"
  }
}

The response includes fields retrieved from the original Yapily Payment even when they're not specified in the refund request. For example, amount and paymentDate.

Once the request is created and validated, in the background, a beneficiary is created and a Pay Out made to execute the request.

To understand when the refund is COMPLETED or FAILED we recommend subscribing to virtualAccount.refund.status event notifications which will alert you to the changes in the refund status.

Retrieve refunds

Get a list of refunds

You can retrieve a list of refunds made using the Get Refunds endpoint. You can provide query parameters to filter the list as required.

You can use the paymentInitiationId query parameter to retrieve a list of all the refunds requested for a specific payment to calculate the total value of refunds to date and the total amount left available to refund.

Example request:

Copy

Copied

curl -L -X GET 'https://api.yapily.com/virtual-accounts/refunds' \
-H 'client-id: <virtual_account_client_id>' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'

Example response:

Copy

Copied

{
  "meta": {
    "tracingId": "96169af01d394ad39658f17d53b49a5d"
  },
  "links": {
    "next": "https://api.yapily.com/virtual-accounts/refunds?cursor=cGF5bWVudEluaXRpYXRpb25JZD1QRENfMjliZDg1MjgtOWI2Zi00YjZlLWE5NjMtOTM4Mjk0NGRjODMwJnN0YXR1cz1GQUlMRUQmY3JlYXRlZERhdGVUaW1lRnJvbT0yMDIzLTAxLTEzVDE2OjQxOjUxLjEzNjA4NVomY3JlYXRlZERhdGVUaW1lVG89MjAyMy0wMi0xMFQxODo0Mjo1MS4xMzYwODVaJnBvaW50ZXI9MjAyMy0wMS0xM1QxNjo0MTo1MS4xMzYwODU="
  },
  "data": [
    {
      "id": "46d3349e-6733-459d-a6da-71850a7e8076",
      "originalPayment": {
        "paymentInitiationId": "19d2fbfb-f30c-44eb-b3b5-978560d2b712"
      },
      "status": "INITIATED",
      "amount": {
        "amount": 100,
        "currency": "GBP"
      },
      "reason": "REQUESTED_BY_CUSTOMER",
      "paymentDate": "2022-11-11",
      "reference": "Ref Order 123",
      "refundTo": "SOURCE",
      "refundToOriginalPayer": true,
      "beneficiaryType": "INDIVIDUAL",
      "createdDateTime": "2022-11-11T15:00:57.345Z",
      "updatedDateTime": "2022-11-11T14:00:57.751Z"
    },
    {
      "id": "b0a6242c-d634-4a5a-bdcc-410c4355e9f8",
      "originalPayment": {
        "paymentInitiationId": "4cb0060a-4aef-4f94-811b-f9356692ca37"
      },
      "status": "COMPLETED",
      "amount": {
        "amount": 20.59,
        "currency": "GBP"
      },
      "reason": "REQUESTED_BY_CUSTOMER",
      "paymentDate": "2022-11-08",
      "reference": "Ref Order 099",
      "refundTo": "SOURCE",
      "refundToOriginalPayer": true,
      "beneficiaryType": "INDIVIDUAL",
      "createdDateTime": "2022-11-08T11:00:57.345Z",
      "updatedDateTime": "2022-11-08T11:22:59.751Z"
    }
  ]
}

Get refund details

You can retrieve information and the status of a specific refund using the get refund endpoint. You must provide the id of the refund you want to retrieve in the path.

Example request:

Copy

Copied

curl -L -X GET 'https://api.yapily.com/virtual-accounts/refunds/{refundId}' \
-H 'client-id: <virtual_account_client_id>' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'

Example response:

Copy

Copied

{
  "data": {
    "id": "46d3349e-6733-459d-a6da-71850a7e8076",
    "originalPayment": {
      "paymentInitiationId": "<ORIGINAL_PAYMENT_ID>"
    },
    "status": "COMPLETED",
    "amount": {
      "amount": 10,
      "currency": "GBP"
    },
    "reason": "REQUESTED_BY_CUSTOMER",
    "paymentDate": "2022-08-28",
    "reference": "Refund 123",
    "beneficiaryType": "INDIVIDUAL",
    "createdDateTime": "2022-04-31T15:00:57.345Z",
    "updatedDateTime": "2022-05-31T14:00:57.751Z"
  }
}

Refund status

Refunds have the same status values as other types of payment as described below:

Status	Description
INITIATED	Refund validated and accepted for processing.
PROCESSING	Refund processing.
SCHEDULED	Refund validated and scheduled for execution on the requested future date.
COMPLETED	Refund successfully processed and funds debited from your account. The payment instruction has been released to the payment scheme and settlement at the beneficiary is expected according to the estimated settlement periods.
FAILED	Refund failed.

Subscribe to virtualAccount.refund.status notifications to be notified of changes in the refund status.

Validation

The following validation rules apply to refund requests:

Error	Description
`REFUND_AMOUNT_MUST_BE_POSITIVE`	Refund amount has to be positive
`PAYMENT_NOT_SETTLED`	Original payment must have settled before requesting a refund
`PAYMENT_INVALID_EXECUTION_DATE`	Payment date must be today or in the future
`REFUND_AMOUNT_EXCEEDS_AMOUNT_LEFT_TO_REFUND`	Total refund amount cannot exceed the original payment amount
`PAYMENT_INVALID_CURRENCY`	Refund currency must match account currency
`PAYMENT_INSUFFICIENT_FUNDS`	Virtual account must have sufficient funds to cover the refund amount

Transfer funds

You can move funds between your virtual accounts when they have the same currency.

Create a transfer

Make a request to the create transfer endpoint, supplying a unique value in the idempotency-key header.

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