Virtual Accounts access

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

Access types

note

Access to Yapily Virtual Accounts must be requested through your Customer Success Manager, who will discuss the type of access you require.

The following access types are available:

Direct access

You wish to hold and operate your own set of accounts.

Virtual Account Direct Access

Partner access

You wish to issue accounts to your clients and operate them on their behalf.

For example, you may wish to issue accounts to the merchants or consumers that you serve.

Virtual Account Partner Access

See clients for more information.

Direct and Partner access

You wish to hold and operate your own set of accounts, as well as those of your clients.

Virtual Account Both Access

Authentication

To authenticate, please follow our authentication guidance.

Client ID header

When making requests to any of the virtual account endpoints, you must include the client-id header.

If you only have direct access and operate on your own accounts, then you will always supply the same identifier that has been assigned to you.

If you have partner access, each of the clients you operate on behalf of will have their own identifier. You must pass the correct identifier that corresponds to the client that your request relates to.

Your client-id, and that of your clients where applicable, will be provided to you at time of onboarding.

Clients

With partner access you can issue virtual accounts to your clients and operate them on their behalf.

You can onboard an unlimited number of clients and each client can be an individual or business entity.

Create a client

You can create a new client using the Create Virtual Account Client endpoint, including the type as individual or business.

Depending on the client type, different fields are required in the request body.

Example request (business)

Copy

Copied

curl -L -X POST 'https://api.yapily.com/virtual-accounts/clients' \
-H 'client-id: <virtual_account_client_id>' \
-H 'Content-Type: application/json' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
   "type": "BUSINESS",
   "business": {
       "name": "Spendwise Ltc",
       "type": "SOLE_TRADER",
       "registrationNumber": "BT846165R3003",
       "registeredAddress": {
           "addressLine1": "59 George Street",
           "addressLine2": "2 3",
           "townName": "WOLVERHAMPTON",
           "postCode": "WV80 0DF",
           "country": "GB"
       },
       "tradingAddress": {
           "addressLine1": "59 George Street",
           "addressLine2": "2 3",
           "townName": "WOLVERHAMPTON",
           "postCode": "WV80 0DF",
           "country": "GB"
       },
       "contactName": "Mr Van Dijk",
           "email": "spendwise@example.com",
           "phone": "447956783777"
   }
}'

Example response (business)

Copy

Copied

{
   "meta": {
       "tracingId": "c534e5402ea34bdb8757435f2b044d1b"
   },
   "data": {
       "id": "c94d5b5e-ecb0-4a10-b0b2-ccd5c393c8ea",
       "type": "BUSINESS",
       "kycStatus": "VERIFIED",
       "status": "ACTIVE",
       "createdDateTime": "2022-08-29T09:52:36.928442Z",
       "business": {
           "name": "Spendwise Ltd",
           "type": "SOLE_TRADER",
           "registrationNumber": "BT846165R3003",
           "registeredAddress": {
               "addressLine1": "59 George Street",
               "addressLine2": "2 3",
               "townName": "WOLVERHAMPTON",
               "postCode": "WV80 0DF",
               "country": "GB"
           },
           "tradingAddress": {
               "addressLine1": "59 George Street",
               "addressLine2": "2 3",
               "townName": "WOLVERHAMPTON",
               "postCode": "WV80 0DF",
               "country": "GB"
           },
           "contactName": "Mr Van Dijk",
           "email": "spendwise@example.com",
           "phone": "447956783777"
       }
   }
}

Example request (individual)

Copy

Copied

curl -L -X POST 'https://api.yapily.com/virtual-accounts/clients' \
-H 'client-id: <virtual_account_client_id>' \
-H'Content-Type: application/json' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
   "type": "INDIVIDUAL",
   "individual": {
       "firstName": "Peter",
       "lastName": "Jones",
       "address": {
           "addressLine1": "59 George Street",
           "addressLine2": "2 3",
           "townName": "WOLVERHAMPTON",
           "postCode": "WV80 0DF",
           "country": "GB"
       },
       "birthDate": "1990-07-10",
       "email": "peter.jones@example.com",
       "phone": "447956783777"
   }
}'

Example response (individual)

Copy

Copied

{
   "meta": {
       "tracingId": "9792bc906b204fbc8f949cd576af555b"
   },
   "data": {
       "id": "e2aaa6bd-0624-43e0-8e8e-e060cbe92398",
       "type": "INDIVIDUAL",
       "kycStatus": "VERIFIED",
       "status": "ACTIVE",
       "createdDateTime": "2022-08-29T09:53:36.732886Z",
       "individual": {
           "firstName": "Peter",
           "lastName": "Jones",
           "address": {
               "addressLine1": "59 George Street",
               "addressLine2": "2 3",
               "townName": "WOLVERHAMPTON",
               "postCode": "WV80 0DF",
               "country": "GB"
           },
           "birthDate": "1990-07-10",
           "email": "peter.jones@example.com",
           "phone": "447956783777"
       }
   }
}

Client properties

ID

Each client with a virtual account has their own client ID. You must pass the corresponding client ID in the client_id header when making a request to operate on a client's virtual account.

Status

Each client has a status which details whether operations can be performed for that client.

The following status apply:

Status	Description
PENDING	The client is being onboarded. It is not yet operational. We recommend subscribing to `virtualAccount.client.status` notifications so you receive a notification when onboarding is complete.
ACTIVE	The client is active and their virtual accounts are operational.
SUSPENDED	The client is currently suspended. You can't perform operations for this client.

KYC status

The KYC status details the current KYC verification status of the client.

Status	Description
UNVERIFIED	The client is not currently fully verified. Required action depends on the KYC model in place for this client.
VERIFIED	The client has been fully verified.

Retrieve your clients

You can retrieve a list of the clients you have onboarded using the Get Virtual Account Clients endpoint.

You can filter the list by providing any of the following query parameters in the request:

type
status

Example request:

Copy

Copied

curl -L -X GET 'https://api.yapily.com/virtual-accounts/clients' \
-H 'client-id: virtual_account_client_id' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'

Example response:

Copy

Copied

{
    "meta": {
        "tracingId": "a08b4214a7734ed0978157afcb13a011"
    },
    "data": [
        {
            "id": "5b7b992a-dc01-4e72-bbcb-4c330051acc7",
            "type": "INDIVIDUAL",
            "kycStatus": "VERIFIED",
            "status": "ACTIVE",
            "createdDateTime": "2022-09-08T13:01:01.886629Z",
            "individual": {
                "firstName": "Peter",
                "lastName": "Jones",
                "address": {
                    "addressLine1": "59 George Street",
                    "addressLine2": "2 3",
                    "townName": "Wolverhampton",
                    "postCode": "WV80 0DF",
                    "country": "GB"
                },
                "birthDate": "1990-07-10",
                "email": "peter.jones@example.com",
                "phone": "447956783777"
            }
        }
    ],
    "links": {
        "self": "https://api.yapily.com/virtual-accounts/clients?cursor=cGFnZT0wJnNpemU9MTAwMCZzb3J0PWNyZWF0ZWREYXRlVGltZSxkZXNj",
        "first": "https://api.yapily.com/virtual-accounts/clients?cursor=cGFnZT0wJnNpemU9MTAwMCZzb3J0PWNyZWF0ZWREYXRlVGltZSxkZXNj",
        "last": "https://api.yapily.com/virtual-accounts/clients?cursor=cGFnZT0wJnNpemU9MTAwMCZzb3J0PWNyZWF0ZWREYXRlVGltZSxkZXNj"
    }
}