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.

Supported currencies

You can hold a number of accounts across multiple currencies. Virtual Accounts are connected to a range of payment schemes for making payments into and out of these accounts.

The following currencies, and their respective payment schemes, are currently supported:

Currency Code	Currency	Hold Virtual Account?	Pay In? (Schemes Supported)	Pay Out? (Schemes Supported)
EUR	Euro	Yes	SEPA CREDIT SEPA INSTANT SWIFT	SEPA CREDIT SEPA INSTANT
GBP	British Pound Sterling	Yes	Faster Payments CHAPS SWIFT	Faster Payments CHAPS

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

Open 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 -L -X POST 'https://api.yapily.com/virtual-accounts/accounts' \
 -H 'client-id: <virtual_account_client_id>' \
 -H 'Content-Type: application/json' \
 -u 'APPLICATION_KEY:APPLICATION_SECRET' \
 -d '{
    "nickname": "Primary Collection Account",
    "currency": "GBP"
}'

Response:

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 is returned as PENDING while 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 can 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.

Get 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 -L -X GET 'https://api.yapily.com/virtual-accounts/accounts/{account-id}' \
    -H 'client-id: <virtual_account_client_id>' \
    -u 'APPLICATION_KEY:APPLICATION_SECRET'

Response:

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

Retrieve accounts

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 -L -X GET 'https://api.yapily.com/virtual-accounts/accounts' \
 -H 'client-id: <virtual_account_client_id>' \
 -u 'APPLICATION_KEY:APPLICATION_SECRET'

Response:

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