All Virtual Accounts

Get All Virtual Accounts

GET /v1/api/virtual-accounts

This endpoint is used to retrieve a paginated list of all client’s virtual accounts, both permanent and transient.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
page-size	Yes	Query	Integer	The number of items or records to return per page
page-number	Yes	Query	Integer	The page number of the request

Sample Request

curl --location '{BASE_URL}/v1/api/virtual-accounts?page-size=10&page-number=1' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}'

Sample Response (200 - OK)

{
    "totalPermanentAccountCount": 2,
    "totalTransientAccountCount": 1,
    "totalCount": 3,
    "status": "SUCCESS",
    "message": "Operation successful.",
    "statusCode": "00",
    "data": [
        {
            "accountNumber": "9000002126",
            "accountName": "TOBI ADELAJA TEST",
            "businessId": "f4eaaa4f-600c-4953-b18d-c49e4f92edcf",
            "accountType": "Transient",
            "autoPayoutEnabled": false,
            "requestReference": "f0150754-ae99-4869-9888-f3e7b89e7486",
            "amount": 200000,
            "isSinglePayment": true,
            "expiresAt": "2024-03-04T13:08:32.788644Z",
            "status": "Closed"
        },
         {
            "accountNumber": "9000003147",
            "accountName": "TOBI ADELAJA 41",
            "businessId": "f4eaaa4f-600c-4953-b18d-c49e4f92edcf",
            "accountType": "Transient",
            "autoPayoutEnabled": false,
            "requestReference": "b0150754-ae99-1112-9888-f3e7b89e7486",
            "amount": null,
            "isSinglePayment": true,
            "expiresAt": "2024-03-04T13:08:32.788644Z",
            "status": "Closed"
        },
        {
            "accountNumber": "9000003147",
            "accountName": "TOBI ADELAJA 33",
            "businessId": "f4eaaa4f-600c-4953-b18d-c49e4f92edcf",
            "accountType": "Transient",
            "autoPayoutEnabled": false,
            "requestReference": "a0150754-ae99-4869-9888-f3e7b89e7486",
            "amount": 350000,
            "isSinglePayment": false,
            "expiresAt": "2024-03-04T13:08:32.788644Z",
            "status": "Closed"
        },
        {
            "accountNumber": "9000002171",
            "accountName": "TOBI ADELAJA 23",
            "businessId": "f4eaaa4f-600c-4953-b18d-c49e4f92edcf",
            "accountType": "Permanent",
            "autoPayoutEnabled": false,
            "requestReference": "d0150754-bd89-4869-9888-f3e7b89e7486",
            "amount": null,
            "isSinglePayment": false,
            "status": "Active"
        },
        {
            "accountNumber": "9000002102",
            "accountName": "TOBI ADELAJA 21",
            "businessId": "f4eaaa4f-600c-4953-b18d-c49e4f92edcf",
            "accountType": "Permanent",
            "autoPayoutEnabled": true,
            "requestReference": "d0150754-bd89-4869-9888-f3e7b89e7486",
            "amount": null,
            "isSinglePayment": false,
            "status": "Active"
        }
    ]
}

Sample Response (400 - Bad Request)

{
    "status": "FAILED",
    "message": "Page Size is required.",
    "statusCode": "09"
}

Get Single Virtual Account

GET /v1/api/virtual-accounts/{account_number}

This endpoint is used to retrieve a single virtual account, irrespective of the account type.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
accountNumber	Yes	Path	String	The account number being retrieved

Sample Request

curl --location '{BASE_URL}/v1/api/virtual-accounts/{account_number}' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}'

Sample Response (200 - OK)

{
    "status": "SUCCESS",
    "message": "Operation successful.",
    "statusCode": "00",
    "data": {
        "accountBalance": 14136086,
        "accountNumber": "9000003680",
        "accountName": "Sylvia TVA1 QA",
        "businessId": "65f3ece0-b29d-4741-a20a-4103a0374f80",
        "accountType": "Permanent",
        "autoPayoutEnabled": true,
        "status": "Active"
    }
}

Sample Response (400 - Bad Request)

{
    "status": "FAILED",
    "message": "Account Number must have a length of 10 characters.",
    "statusCode": "09"
}

Sample Response (404 - Not Found)

{
    "status": "FAILED",
    "message": "No record found.",
    "statusCode": "25"
}

Get Account Balance Summary

GET /v1/api/virtual-accounts/total-balance

This endpoint is used to retrieve the aggregate balance of all virtual accounts.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made

Sample Request

curl --location '{BASE_URL}/v1/api/virtual-accounts/total-balance' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}'

Sample Response (200 - OK)

{
    "status": "SUCCESS",
    "message": "Operation successful.",
    "statusCode": "00",
    "data": {
        "totalPermanentAccountBalance": 14211668,
        "totalTransientAccountBalance": 16800000,
        "totalVirtualAccountBalance": 31011668
    }
}

Note

All balances are in kobo.