Virtual Accounts

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 hold an unlimited number of accounts across the currencies we support. Therefore, you can segregate funds and payment receipts in any way that you choose.

Each account you hold retains its own funds and has routing & identification information (such as an IBAN) that allows you make and receive payments.

Key Account Properties

Account Status

The account status indicates whether it is currently operational or not.

The available values are described below:

State Description
PENDING The account creation process is still in progress.
The account is not yet ready for use
ACTIVE The account has been created and is ready for use
FAILED The account creation processed failed
SUSPENDED The account has been temporarily suspended and cannot be used to make payments as this time
CLOSED The account has been permanently closed. It is not available for use

Account status life cycle diagram:

Virtual Account Status

Account Identifications

The bankAccount provides details of the underlying account holding institution. This includes the accountIdentifications (e.g. IBAN, Sort Code) for the account that you can use to pay money into it. The bankAccount will not be returned when the account is in a PENDING state.

Account Balances

The balances report the current, live balances of the account, including:

  • An INTERIM_BOOKED balance which states the current, full position of the account including pending transactions
  • An INTERIM_AVAILABLE balance denoting the funds that are available to use / spend

Opening a new account

You can open a new account through the Create Account endpoint, specifying the desired currency and a nickname that will help you identify the account.

Request:

Copy
Copied
curl --location --request POST 'https://api.yapily.com/virtual-accounts/accounts' \
 --header 'client-id: <virtual_account_client_id>' \
 --header 'Authorization: Bearer <access_token>' \
 --header 'Content-Type: application/json' \
 --data-raw '{
    "nickname": "Primary Collection Account",
    "currency": "GBP"
}'

A successful response will appear as below:

Copy
Copied
{
   "meta": {
       "tracingId": "ce936f4d24384b89ae08227a8058b701"
   },
   "data": {
       "id": "903cac72-debf-4ace-8746-7dcde11293ae",
       "createdDateTime": "2022-06-30T16:26:10.85Z",
       "status": "PENDING",
       "nickname": "Primary Collection Account",
       "currency": "GBP",
       "balances": [
           {
               "type": "INTERIM_AVAILABLE",
               "balanceAmount": {
                   "amount": 0.0,
                   "currency": "GBP"
               }
           },
           {
               "type": "INTERIM_BOOKED",
               "balanceAmount": {
                   "amount": 0.0,
                   "currency": "GBP"
               }
           }
       ],
       "bankAccount": {
           "currency": "GBP",
           "accountIdentifications": []
       }
   }
}

The status of the account will be returned as PENDING whilst the account opening process is in progress. This normally takes a few seconds and we recommend subscribing to virtualAccounts.account.status notifications so that we notify you once it has completed.

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

Getting Account Information

You can retrieve information about an account by using the Get Account endpoint. You need to specify the id of the account you wish to retrieve in the path.

Request:

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

A successful response will appear as below:

Copy
Copied
{
   "meta": {
       "tracingId": "33e93bd14e4f40159157cc688ad822cc"
   },
   "data": {
       "id": "903cac72-debf-4ace-8746-7dcde11293ae",
       "createdDateTime": "2022-06-30T16:26:10.85Z",
       "status": "ACTIVE",
       "nickname": "Primary Collection Account",
       "currency": "GBP",
       "balances": [
           {
               "type": "INTERIM_AVAILABLE",
               "balanceAmount": {
                   "amount": 0.0,
                   "currency": "GBP"
               }
           },
           {
               "type": "INTERIM_BOOKED",
               "balanceAmount": {
                   "amount": 0.0,
                   "currency": "GBP"
               }
           }
       ],
       "bankAccount": {
           "currency": "GBP",
           "bankName": "GlobalBank",
           "bankAddress": "200 Old Street, London, England, EC1 9LE",
           "bankCountry": "GB",
           "accountIdentifications": [
               {
                   "type": "BIC",
                   "identification": "SEOUGB21"
               },
               {
                   "type": "IBAN",
                   "identification": "GB27SMLT04050900005500"
               },
               {
                   "type": "SORT_CODE",
                   "identification": "040509"
               },
               {
                   "type": "ACCOUNT_NUMBER",
                   "identification": "00005500"
               }
           ]
       }
   }
}

Retrieving the accounts you hold

You can retrieve a list of the accounts you currently hold using the Get Accounts endpoint, providing any of the available query parameters to filter the list as required.

Request:

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

A successful response will appear as below:

Copy
Copied
{
   "meta": {
       "tracingId": "fe8486ab776d4652a86a9c0e5bfced59"
   },
   "links": {
       "next": "https://api.yapily.com/virtual-accounts/accounts?cursor=cGFnZT0xJnNpemU9MTAwMA==",
       "last": "https://api.yapily.com/virtual-accounts/accounts?cursor=cGFnZT0yOSZzaXplPTEwMDA=",
       "self": "https://api.yapily.com/virtual-accounts/accounts?cursor=cGFnZT0wJnNpemU9MTAwMA==",
       "first": "https://api.yapily.com/virtual-accounts/accounts?cursor=cGFnZT0wJnNpemU9MTAwMA=="
   },
   "data": [
       {
           "id": "a182d717-8adb-4b6e-adea-964be26aedf9",
           "createdDateTime": "2022-06-28T09:38:24.856Z",
           "status": "ACTIVE",
           "nickname": "My USD Funds",
           "currency": "USD",
           "balances": [
               {
                   "type": "INTERIM_AVAILABLE",
                   "balanceAmount": {
                       "amount": 0.0,
                       "currency": "USD"
                   }
               },
               {
                   "type": "INTERIM_BOOKED",
                   "balanceAmount": {
                       "amount": 0.0,
                       "currency": "USD"
                   }
               }
           ],
           "bankAccount": {
               "currency": "USD",
               "bankName": "GlobalBank",
               "bankAddress": "200 Old Street, London, England, EC1 9LE",
               "bankCountry": "MT",
               "accountIdentifications": [
                   {
                       "type": "BIC",
                       "identification": "CFTEMTM1"
                   },
                   {
                       "type": "ACCOUNT_NUMBER",
                       "identification": "000000090010004567"
                   },
                   {
                       "type": "IBAN",
                       "identification": "MT45CFTE19870000000090010004567"
                   }
               ]
           }
       },
       {
           "id": "ea2c7443-d9ff-4fc1-bb7d-0cc2e84435cc",
           "createdDateTime": "2022-06-30T16:25:00.713Z",
           "status": "ACTIVE",
           "nickname": "My GBP Funds",
           "currency": "GBP",
           "balances": [
               {
                   "type": "INTERIM_AVAILABLE",
                   "balanceAmount": {
                       "amount": 0.0,
                       "currency": "GBP"
                   }
               },
               {
                   "type": "INTERIM_BOOKED",
                   "balanceAmount": {
                       "amount": 0.0,
                       "currency": "GBP"
                   }
               }
           ],
           "bankAccount": {
               "currency": "GBP",
               "bankName": "GlobalBank",
               "bankAddress": "200 Old Street, London, England, EC1 9LE",
               "bankCountry": "GB",
               "accountIdentifications": [
                   {
                       "type": "IBAN",
                       "identification": "GB54SMLT04050900005499"
                   },
                   {
                       "type": "BIC",
                       "identification": "SEOUGB21"
                   },
                   {
                       "type": "ACCOUNT_NUMBER",
                       "identification": "00005499"
                   },
                   {
                       "type": "SORT_CODE",
                       "identification": "040509"
                   }
               ]
           }
       }
   ]
}