Virtual Accounts clients

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

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