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:
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_BOOKEDbalance which states the current, full position of the account including pending transactions -
An
INTERIM_AVAILABLEbalance 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:
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:
{
"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:
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:
{
"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:
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:
{
"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"
}
]
}
}
]
}