Beneficiaries

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

A beneficiary is any entity to whom you wish to make a Pay Out.

Examples of a beneficiary include:

  • Your business account
  • An account of one of your merchant clients
  • An account of one of your consumers

Create a new beneficiary

You can create a new beneficiary using the Create Beneficiary endpoint.

The required details for the beneficiary differ according to its bankCountry and currency:

bankCountry currency Property Requirements
GB GBP PaymentSchemes Mandatory

Must only include:
  • FASTER_PAYMENTS
  • CHAPS
sortCode Mandatory

Must be 6 digits
accountNumber Mandatory

Must be 8 or 9 digits
Any SEPA zone country EUR PaymentSchemes Mandatory

Must only include:
  • SEPA_CREDIT
  • SEPA_INSTANT
IBAN Mandatory

Example request:

Copy
Copied
curl -L -X POST 'https://api.yapily.com/virtual-accounts/beneficiaries' \
 -H 'client-id: <virtual_account_client_id>'\
 -H 'Content-Type: application/json' \
 -u 'APPLICATION_KEY:APPLICATION_SECRET' \
 -d '{
   "nickname": "Johns Account",
   "type": "INDIVIDUAL",
   "name": "Johns Account",
   "birthDate": "1999-01-01",
   "paymentSchemes": ["FASTER_PAYMENTS", "CHAPS"],
   "address": {
       "addressLine": "59 George Street",
       "townName": "WOLVERHAMPTON",
       "postCode": "WV80 0DF",
       "country": "GB"
   },
   "account": {
       "currency": "GBP",
       "bankName": "Bank of Ireland",
       "bankAddress": "166 Richmond Road BRISTOL BS75 5ZD",
       "bankCountry": "GB",
       "accountIdentifications": [
           {
               "type": "SORT_CODE",
               "identification": "902127"
           },
           {
               "type": "BIC",
               "identification": "89113"
           },
           {
               "type": "ACCOUNT_NUMBER",
               "identification": "03183419"
           }
       ]
   }
}'

Example response:

Copy
Copied
{
    "meta": {
       "tracingId": "bc09be9769864917b97cc3fc76bd6d36"
   },
   "data": {
       "id": "0d2b7502-26f1-4f44-adb2-aaf0e63c7774",
       "paymentSchemes": [
           "CHAPS",
           "FASTER_PAYMENTS"
       ],
       "nickname": "Johns account",
       "type": "INDIVIDUAL",
       "name": "John Smith",
       "birthDate": "1999-01-01",
       "address": {
           "addressLine": "59 George Street",
           "townName": "WOLVERHAMPTON",
           "postCode": "WV80 0DF",
           "country": "GB"
       },
       "account": {
           "currency": "GBP",
           "bankName": "BANK OF IRELAND (UK) PLC",
           "bankAddress": "4-8 High Street ",
           "bankCountry": "GB",
           "accountIdentifications": [
               {
                   "type": "SORT_CODE",
                   "identification": "902127"
               },
               {
                   "type": "BIC",
                   "identification": "BOFIGB2BXXX"
               },
               {
                   "type": "ACCOUNT_NUMBER",
                   "identification": "03183419"
               }
           ]
       },
       "status": "ACTIVE"
   }
}

A status of ACTIVE indicates that the beneficiary is ready for use.

When the beneficiary is still being created, the status will be returned as PENDING. We recommend subscribing to virtualAccounts.createBeneficiary.status notifications so that you receive a notification when it has completed.

Alternatively, you can use the id that was included in the response to check the status using the Get Beneficiary endpoint.

Get beneficiary information

You can retrieve information about a beneficiary by using the Get Beneficiary endpoint. You must specify the id of the beneficiary in the request path.

Example request:

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

Example response:

Copy
Copied
{
   "meta": {
       "tracingId": "e41b909e61cf480bacfd123557e0c9c1"
   },
   "data": {
       "id": "85f39962-08e8-4ea3-ba49-fd1d715f3b4f",
       "paymentSchemes": [
           "FASTER_PAYMENTS"
       ],
       "nickname": "Johns account",
       "type": "INDIVIDUAL",
       "name": "John Smith",
       "birthDate": "1999-01-01",
       "address": {
           "addressLine": "123 Union Street",
           "townName": "London",
           "postCode": "SE1 1SZ",
           "country": "GB"
       },
       "account": {
           "currency": "GBP",
           "bankName": "MONZO BANK LIMITED",
           "bankAddress": "Broadwalk House 5 Appold Street ",
           "bankCountry": "GB",
           "accountIdentifications": [
               {
                   "type": "IBAN",
                   "identification": "NL15ABNA9287436010"
               },
               {
                   "type": "BIC",
                   "identification": "MONZGB2LXXX"
               },
               {
                   "type": "ACCOUNT_NUMBER",
                   "identification": "03183419"
               },
               {
                   "type": "SORT_CODE",
                   "identification": "040004"
               }
           ]
       },
       "status": "ACTIVE"
   }
}

Retrieve all beneficiaries

You can retrieve a list of all your beneficiaries using the Get Beneficiaries endpoint.

Example request:

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

Example response:

Copy
Copied
{
   "meta": {
       "tracingId": "3c882272b36b4549a8df84e7a5a4a09f"
   },
   "links": {
       "next": "https://api.yapily.com/virtual-accounts/beneficiaries?cursor=cGFnZT0xJnNpemU9MTAwMA==",
       "last": "https://api.yapily.com/virtual-accounts/beneficiaries?cursor=cGFnZT0yMCZzaXplPTEwMDA=",
       "self": "https://api.yapily.com/virtual-accounts/beneficiaries?cursor=cGFnZT0wJnNpemU9MTAwMA==",
       "first": "https://api.yapily.com/virtual-accounts/beneficiaries?cursor=cGFnZT0wJnNpemU9MTAwMA=="
   },
   "data": [
       {
           "id": "85f39962-08e8-4ea3-ba49-fd1d715f3b4f",
           "paymentSchemes": [
               "FASTER_PAYMENTS"
           ],
           "nickname": "Johns Account",
           "type": "INDIVIDUAL",
           "name": "John Smith",
           "birthDate": "1999-01-01",
           "address": {
               "addressLine": "123 Union Street",
               "townName": "London",
               "postCode": "SE1 1SZ",
               "country": "GB"
           },
           "account": {
               "currency": "GBP",
               "bankName": "MONZO BANK LIMITED",
               "bankAddress": "Broadwalk House 5 Appold Street ",
               "bankCountry": "GB",
               "accountIdentifications": [
                   {
                       "type": "IBAN",
                       "identification": "NL15ABNA9287436010"
                   },
                   {
                       "type": "SORT_CODE",
                       "identification": "040004"
                   }
               ]
           },
           "status": "ACTIVE"
       },
{...}