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.
Get Single Account Balance
GET /v1/api/virtual-accounts/balance/{account_number}
This endpoint is used to retrieve the balance of an account. (Virtual or Business account).
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 for which balance is to be retrieved |
Sample Request
curl --location '{BASE_URL}/v1/api/virtual-accounts/balance/{account_number}' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}'
Sample Response (200 - OK)
{
"status": "SUCCESS",
"message": "Operation successful.",
"statusCode": "00",
"data": {
"accountBalance": 31928592
}
}
Note
All balances are in kobo.