USD Virtual Accounts allow you to receive US Dollar payments directly into your meCash wallet via SWIFT transfers. These accounts are ideal for businesses that need to collect international payments in USD.
Sales Approval Required: USD Virtual Accounts require prior approval. Please contact Sales to request access before attempting to create a USD virtual account. Key Features
- Permanent Account: Once created, your USD virtual account remains active indefinitely
- SWIFT Enabled: Receive international wire transfers via SWIFT
- Business-Ready: Designed for corporate collections with company registration requirements
- Global Reach: Accept USD payments from anywhere in the world
Prerequisites
Before creating a USD Virtual Account, ensure you have:
- Sales Approval: Contact Sales to enable USD virtual accounts for your workspace
- Company Registration Details: You’ll need your business registration number, country, and date
- KYC Information: Valid identification for the authorized representative
How it Works
Request Fields
| Field | Type | Required | Description |
|---|
currency | String | Yes | Must be USD |
country | String | Yes | Must be US |
firstName | String | Yes | Authorized representative’s first name |
lastName | String | Yes | Authorized representative’s last name |
email | String | Yes | Contact email address |
phoneNumber | String | Yes | Phone number in international format |
reference | String | Yes | Your unique reference for idempotency |
accountName | String | Yes | Business/account display name |
gender | String | Yes | Gender of representative (M or F) |
dateOfBirth | String | Yes | Date of birth (YYYY-MM-DD format) |
nationality | String | Yes | 2-letter ISO country code |
idType | String | Yes | Type of ID (e.g., PASSPORT, NATIONAL_ID) |
idNumber | String | Yes | ID document number |
address | String | Yes | Street address |
city | String | Yes | City or town |
postalCode | String | Yes | Postal/ZIP code |
company | Object | Yes | Company registration details |
company.registrationNumber | String | Yes | Business registration number |
company.registrationCountry | String | Yes | 2-letter ISO country code where company is registered |
company.registrationDate | String | Yes | Date of registration (YYYY-MM-DD format) |
Request Example
curl --request POST '{{baseURL}}/v1/virtual-account' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"currency": "USD",
"country": "US",
"firstName": "John",
"lastName": "Mary",
"email": "[email protected]",
"phoneNumber": "+2348156936458",
"reference": "REF_8899562444KLLTTPL90",
"accountName": "Test Ng Ltd",
"gender": "M",
"dateOfBirth": "1980-10-10",
"nationality": "NG",
"idType": "PASSPORT",
"idNumber": "C234567890",
"address": "Brown Way",
"city": "Lagos",
"postalCode": "100001",
"company": {
"registrationNumber": "NG1235687",
"registrationCountry": "NG",
"registrationDate": "2024-10-10"
}
}'
Response Example
{
"message": "virtual account created successfully",
"status": "success",
"data": {
"firstName": "John",
"lastName": "Mary",
"email": "[email protected]",
"phoneNumber": "+2348156936458",
"reference": "REF_8899562444KLLTTPL90",
"accountName": "Test Ng Ltd",
"gender": "M",
"dateOfBirth": "1980-10-10",
"nationality": "NG",
"idType": "PASSPORT",
"idNumber": "********",
"address": "Brown Way",
"city": "Lagos",
"postalCode": "100001",
"status": "PROCESSING",
"currency": "USD",
"country": "US",
"isPermanent": true,
"company": {
"registrationNumber": "NG1235687",
"registrationCountry": "NG",
"registrationDate": "2024-10-10"
}
}
}
Response Fields
| Field | Type | Description |
|---|
message | String | Operation status message |
status | String | API request status |
data.id | String | Unique identifier for the virtual account |
data.firstName | String | Authorized representative’s first name |
data.lastName | String | Authorized representative’s last name |
data.email | String | Contact email tied to the account |
data.phoneNumber | String | Phone number stored for the customer |
data.reference | String | Your unique reference for idempotency |
data.accountName | String | Display name for the account (Business Name) |
data.gender | String | Gender of the representative (M or F) |
data.dateOfBirth | String | Date of birth (YYYY-MM-DD) |
data.nationality | String | 2-letter ISO country code of nationality |
data.idType | String | Type of identification provided |
data.idNumber | String | ID number (masked in response) |
data.address | String | Street address |
data.city | String | City or Town |
data.postalCode | String | Postal/ZIP code |
data.account.name | String | Display name on the bank account |
data.account.bankName | String | Issuing bank for the virtual account |
data.account.sortCode | String | Bank sort code |
data.account.number | String | Account number for receiving funds (received via webhook) |
data.account.swiftCode | String | SWIFT/BIC code for international transfers (received via webhook) |
data.status | String | Account status (e.g., PROCESSING, ACTIVE) |
data.currency | String | ISO 4217 currency code (USD) |
data.country | String | ISO 3166-1 alpha-2 country code (US) |
data.isPermanent | Boolean | Always true for USD virtual accounts |
data.company | Object | Company registration details |
data.company.registrationNumber | String | Business registration number |
data.company.registrationCountry | String | Country where company is registered |
data.company.registrationDate | String | Date of company registration |
Asynchronous Details: For USD virtual accounts, the bank account details (account.number, account.swiftCode, etc.) are not available immediately. You will receive them via the virtualaccount.creation.completed webhook once processing is complete.
Sharing Account Details
When sharing the account details with your customers for SWIFT transfers, provide:
- Account Number: The
account.number field
- Bank Name: The
account.bankName field
- SWIFT/BIC Code: The
account.swiftCode field
- Account Name: The
account.name field
Always include the SWIFT code when sharing account details for international transfers. This ensures funds are routed correctly.
Error Responses
| Status | Message | Cause | How to Fix |
|---|
| 400 | USD virtual accounts not enabled | Your workspace doesn’t have USD virtual accounts enabled | Contact Sales to request access |
| 400 | Company registration details required | Missing company object in request | Include all required company registration fields |
| 400 | Invalid company registration country | Invalid ISO country code in company.registrationCountry | Use a valid 2-letter ISO country code |
| 400 | Invalid date format | Incorrect date format for dateOfBirth or registrationDate | Use YYYY-MM-DD format |
| 401 | API key missing or incorrect | Invalid or missing API key | Include correct x-api-key header |
| 409 | Reference must be unique | The reference has been used before | Use a unique reference value |
Webhooks
The USD virtual account lifecycle involves two primary webhook events:
virtualaccount.creation.completed: Sent when the USD account has been successfully provisioned. This contains the account number and SWIFT details.virtualaccount.completed: Sent when funds are deposited into your USD virtual account.
See USD Virtual Account Webhook for payload details.
Best Practices
- Monitor Creation Webhook: Subscribe to
virtualaccount.creation.completed to receive account details automatically
- Verify Company Details: Ensure company registration details are accurate to avoid processing delays
- Monitor Deposits: Subscribe to
virtualaccount.completed events to track incoming deposits in real-time
