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

Creating a new beneficiary

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

The details that must be supplied 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

Request:

Copy
Copied
curl --location --request POST 'https://api.yapily.com/virtual-accounts/beneficiaries' \
 --header 'client-id: <virtual_account_client_id>'\
 --header 'Authorization: Bearer <access_token>' \
 --header 'Content-Type: application/json' \
 --data-raw '{
   "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"
           }
       ]
   }
}'

A successful response will appear as below:

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

The status of the beneficiary may be returned as PENDING whilst the creation process is in progress. We recommend subscribing to virtualAccounts.createBeneficiary.status notifications so that we notify you once it has completed.

Alternatively, you can use the id that was included in the response to check the status using the Get Beneficiary endpoint. A status of ACTIVE indicates that the beneficiary is ready for use.

Getting beneficiary information

You can retrieve information about a beneficiary by using the Get Beneficiary endpoint. You need to specify the id of the beneficiary you wish to retrieve in the path.

Request:

Copy
Copied
curl --location --request GET 'https://api.yapily.com/virtual-accounts/beneficiaries/{beneficiary-id}' \
 --header 'client-id:<virtual_account_client_id>'\
 --header 'Authorization: Bearer <access_token>'

A successful response will appear as below:

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

Retrieving all the beneficiaries

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

Request:

Copy
Copied
curl --location --request GET 'https://api.yapily.com/virtual-accounts/beneficiaries' \
 --header 'client-id:<virtual_account_client_id>'\
 --header 'Authorization: Bearer <access_token>'

A successful response will appear as below:

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"
       },
{...}