Skip to main content
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:
  1. Sales Approval: Contact Sales to enable USD virtual accounts for your workspace
  2. Company Registration Details: You’ll need your business registration number, country, and date
  3. KYC Information: Valid identification for the authorized representative

​
How it Works

​
Request Fields

FieldTypeRequiredDescription
currencyStringYesMust be USD
countryStringYesMust be US
firstNameStringYesAuthorized representative’s first name
lastNameStringYesAuthorized representative’s last name
emailStringYesContact email address
phoneNumberStringYesPhone number in international format
referenceStringYesYour unique reference for idempotency
accountNameStringYesBusiness/account display name
genderStringYesGender of representative (M or F)
dateOfBirthStringYesDate of birth (YYYY-MM-DD format)
nationalityStringYes2-letter ISO country code
idTypeStringYesType of ID (e.g., PASSPORT, NATIONAL_ID)
idNumberStringYesID document number
addressStringYesStreet address
cityStringYesCity or town
postalCodeStringYesPostal/ZIP code
companyObjectYesCompany registration details
company.registrationNumberStringYesBusiness registration number
company.registrationCountryStringYes2-letter ISO country code where company is registered
company.registrationDateStringYesDate 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": "someothis@gmail.com",
  "phoneNumber": "+2348156936458",
  "reference": "REF_8899562444KLLOPLTTPKNMTYLP900POLOPI",
  "accountName": "CHECK 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": "someothis@gmail.com",
        "phoneNumber": "+2348156936458",
        "reference": "REF_8899562444KLLOPLTTPKNMTYLP900POLOPI",
        "accountName": "CHECK 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"
        }
    }
}
Account Details via Webhook: For USD virtual accounts, the actual account number, bank name, and SWIFT details are delivered asynchronously. Once the account is ready, meCash will send a virtualaccount.creation.completed webhook to your configured endpoint.For more details on the payload, see the Virtual Account Creation Webhook documentation.

​
Response Fields

FieldTypeDescription
messageStringOperation status message
statusStringAPI request status
data.idStringUnique identifier for the virtual account
data.firstNameStringAuthorized representative’s first name
data.lastNameStringAuthorized representative’s last name
data.emailStringContact email tied to the account
data.phoneNumberStringPhone number stored for the customer
data.referenceStringYour unique reference for idempotency
data.accountNameStringDisplay name for the account (Business Name)
data.genderStringGender of the representative (M or F)
data.dateOfBirthStringDate of birth (YYYY-MM-DD)
data.nationalityString2-letter ISO country code of nationality
data.idTypeStringType of identification provided
data.idNumberStringID number (masked in response)
data.addressStringStreet address
data.cityStringCity or Town
data.postalCodeStringPostal/ZIP code
data.account.nameStringDisplay name on the bank account
data.account.bankNameStringIssuing bank for the virtual account
data.account.sortCodeStringBank sort code
data.account.numberStringAccount number for receiving funds
data.account.swiftCodeStringSWIFT/BIC code for international transfers
data.statusStringAccount status (ACTIVE, SUSPENDED, etc.)
data.currencyStringISO 4217 currency code (USD)
data.countryStringISO 3166-1 alpha-2 country code (US)
data.isPermanentBooleanAlways true for USD virtual accounts
data.createdStringISO 8601 timestamp when the account was created
data.companyObjectCompany registration details
data.company.registrationNumberStringBusiness registration number
data.company.registrationCountryStringCountry where company is registered
data.company.registrationDateStringDate of company registration

​
Sharing Account Details

When sharing the account details with your customers for SWIFT transfers, provide:
  1. Account Number: The account.number field
  2. Bank Name: The account.bankName field
  3. SWIFT/BIC Code: The account.swiftCode field
  4. 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

StatusMessageCauseHow to Fix
400USD virtual accounts not enabledYour workspace doesn’t have USD virtual accounts enabledContact Sales to request access
400Company registration details requiredMissing company object in requestInclude all required company registration fields
400Invalid company registration countryInvalid ISO country code in company.registrationCountryUse a valid 2-letter ISO country code
400Invalid date formatIncorrect date format for dateOfBirth or registrationDateUse YYYY-MM-DD format
401API key missing or incorrectInvalid or missing API keyInclude correct x-api-key header
409Reference must be uniqueThe reference has been used beforeUse a unique reference value

​
Webhooks

When funds are deposited into your USD virtual account, you’ll receive a virtualaccount.completed webhook. See USD Virtual Account Webhook for payload details.

​
Best Practices

  • Store Account Details: Save the response so you can share the account number and SWIFT code without additional API calls
  • Use Unique References: Always provide a unique reference for each virtual account creation request
  • Verify Company Details: Ensure company registration details are accurate to avoid delays
  • Monitor Webhooks: Subscribe to virtualaccount.completed events to track incoming deposits in real-time

API Reference

View the OpenAPI specification for creating virtual accounts

USD Webhook Events

Learn about USD virtual account webhook payloads