const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
currency: 'NGN',
country: 'NG',
firstName: 'Jumoke',
lastName: 'Dumebi',
email: 'example@email.com',
phoneNumber: '+23481345XXXX',
bvn: '12345678901',
reference: '00006597506292872311029472',
accountName: 'Jumoke Dumebi'
})
};
fetch('https://sandboxapi.me-cash.com/v1/virtual-account', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"message": "virtual account created successfully",
"status": "success",
"data": {
"id": "e21f7365-4fc9-4669-a9d9-xxxxxxxxxxxxx",
"firstName": "Jumoke",
"lastName": "Dumebi",
"email": "example@email.com",
"phoneNumber": "+23481345XXXXX",
"reference": "00006597506292872311029472",
"account": {
"name": "Jumoke Dumebi",
"bankName": "Mock Bank",
"sortCode": null,
"number": "881725XXXXX"
},
"status": "ACTIVE",
"currency": "NGN",
"country": "NG",
"created": "2025-05-15T13:39:57.405Z"
}
}Virtual Account
Create Static Virtual Account
Creates a permanent virtual account for a user, tied to their identity. We support the following currencies: NGN, MWK, USD.
POST
/
v1
/
virtual-account
const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
currency: 'NGN',
country: 'NG',
firstName: 'Jumoke',
lastName: 'Dumebi',
email: 'example@email.com',
phoneNumber: '+23481345XXXX',
bvn: '12345678901',
reference: '00006597506292872311029472',
accountName: 'Jumoke Dumebi'
})
};
fetch('https://sandboxapi.me-cash.com/v1/virtual-account', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"message": "virtual account created successfully",
"status": "success",
"data": {
"id": "e21f7365-4fc9-4669-a9d9-xxxxxxxxxxxxx",
"firstName": "Jumoke",
"lastName": "Dumebi",
"email": "example@email.com",
"phoneNumber": "+23481345XXXXX",
"reference": "00006597506292872311029472",
"account": {
"name": "Jumoke Dumebi",
"bankName": "Mock Bank",
"sortCode": null,
"number": "881725XXXXX"
},
"status": "ACTIVE",
"currency": "NGN",
"country": "NG",
"created": "2025-05-15T13:39:57.405Z"
}
}The Virtual accounts creation details are also sent via webhook.
For USD Virtual Accounts, the API response will have a
PROCESSING status. You must listen for the virtualaccount.creation.completed webhook to receive the full account details (Account Number, Bank Name, etc.).
FOR NGN AND MWK Virtual Accounts, the API response and Webhook will have the account creation details.Error responses
Use this table as the source of truth for troubleshootingPOST /v1/virtual-account.
| Status | Message | What it means | How to fix |
|---|---|---|---|
| 400 | Invalid country or currency ISO code | The country/currency pair is not supported for virtual accounts. | Send valid ISO codes that match an enabled corridor. |
| 400 | Phone number must include valid country code | phoneNumber is missing a proper international prefix. | Format phone numbers with the full country code (for example +234...). |
| 400 | Request JSON malformed or missing required fields | The payload is missing mandatory keys or is not valid JSON. | Validate that fields such as currency, country, reference, and accountName are present before calling the API. |
| 400 | BVN is required | The Nigerian BVN field is absent when it is mandatory. | Provide the 11-digit bvn for NGN accounts. |
| 401 | API key missing or incorrect | Authentication header is missing, invalid, or expired. | Ensure the x-api-key is included for the correct environment. |
| 409 | Reference must be unique | The reference has already been used for another request. | Reuse the initial response or send a new, unique reference. |
| 500 | Service temporarily unavailable | Temporary backend/database outage prevented the request from succeeding. | Retry with backoff or contact support if it persists. |
Authorizations
Body
application/json
- NGN Virtual Account
- MWK Virtual Account
- USD Virtual Account
Virtual account details for Nigeria (NGN).
Currency code (e.g., NGN).
Available options:
NGN Country code (e.g., NG).
Available options:
NG The customer's first name.
The customer's last name.
The customer's email address.
The customer's phone number. This must include the country code.
A unique reference for the request (max 30 characters).
The desired name for the virtual account.
The customer's 11-digit Bank Verification Number.
Was this page helpful?
⌘I