> ## Documentation Index > Fetch the complete documentation index at: https://developer.me-cash.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Static Virtual Account > Creates a permanent virtual account for a user, tied to their identity. We support the following currencies: NGN, MWK, USD. **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/virtualaccount-creation-webhook) 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 troubleshooting `POST /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. | ## OpenAPI ````yaml post /v1/virtual-account openapi: 3.0.3 info: title: meCash API version: 3.0.3 description: >- API for meCash services, including FIAT and Ramp operations. This is the OpenAPI specification for the meCash API, covering all available endpoints for wallet management, currency quotes, and payouts. It follows a design-first approach based on OpenAPI 3.0. Authentication is handled via an API key passed in the `x-api-key` header. Replace `YOUR_API_KEY` with your actual key when making requests. Some useful links: - [meCash Documentation](https://docs.me-cash.com/) - [Authentication Guide](https://docs.me-cash.com/authentication) servers: - url: https://sandboxapi.me-cash.com description: Sandbox Server for Testing security: - ApiKeyAuth: [] tags: - name: Wallet description: Wallet management operations - name: Quote description: Currency quote operations - name: Payout description: Payout operations - name: Transaction description: Transaction management - name: Virtual Account description: Virtual account operations for static and dynamic accounts - name: Bank description: Bank account and list operations - name: Ramp description: Ramp operations for crypto - name: Miscellaneous description: Utility and miscellaneous operations - name: Collection description: Mobile money and wallet funding operations - name: Bulk Payout description: >- Bulk transfer operations for sending to multiple beneficiaries in a single request paths: /v1/virtual-account: post: tags: - Virtual Account summary: Create Static Virtual Account description: >- Creates a permanent virtual account for a user, tied to their identity. We support the following currencies: NGN, MWK, USD. operationId: createStaticVirtualAccount requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateStaticVirtualAccountRequest' examples: NGN_Example: summary: Nigeria (NGN) Example value: currency: NGN country: NG firstName: Jumoke lastName: Dumebi email: example@email.com phoneNumber: +23481345XXXX bvn: '12345678901' reference: '00006597506292872311029472' accountName: Jumoke Dumebi MWK_Example: summary: Malawi (MWK) Example value: currency: MWK country: MW firstName: Corrine lastName: Schinner email: kathl@example.com phoneNumber: +265813XXXXXX reference: 000033556X accountName: Corrine Schinner USD_Example: summary: United States (USD) Example value: currency: USD country: US firstName: Jolie lastName: Beahan email: Sim42@yahoo.com phoneNumber: 711-442-7768 reference: REF_XNUQ4GXT0DMB accountName: Mrs. Alison Berge gender: M dateOfBirth: '1980-10-10' nationality: NG idType: PASSPORT idNumber: ARZATFP1 address: 37469 Stokes Path city: Deshaunstad postalCode: '100001' company: registrationNumber: NOOELBN1089 registrationCountry: NG registrationDate: '2024-10-10' responses: '200': $ref: '#/components/responses/CreateStaticVAccountSuccess' '400': $ref: '#/components/responses/StaticVAccountBadRequest' '401': $ref: '#/components/responses/PayoutUnauthorized' '409': $ref: '#/components/responses/DynamicVAccountConflict' '500': $ref: '#/components/responses/PayoutInternalServerError' components: schemas: CreateStaticVirtualAccountRequest: type: object description: >- Request to create a static virtual account. The required fields depend on the selected currency. oneOf: - $ref: '#/components/schemas/NgnVirtualAccountRequest' - $ref: '#/components/schemas/MwkVirtualAccountRequest' - $ref: '#/components/schemas/UsdVirtualAccountRequest' discriminator: propertyName: currency mapping: NGN: $ref: '#/components/schemas/NgnVirtualAccountRequest' MWK: $ref: '#/components/schemas/MwkVirtualAccountRequest' USD: $ref: '#/components/schemas/UsdVirtualAccountRequest' NgnVirtualAccountRequest: title: NGN Virtual Account description: Virtual account details for Nigeria (NGN). allOf: - $ref: '#/components/schemas/BaseVirtualAccountRequest' - type: object required: - bvn properties: currency: type: string description: Currency code (e.g., NGN). enum: - NGN country: type: string description: Country code (e.g., NG). enum: - NG bvn: type: string description: The customer's 11-digit Bank Verification Number. MwkVirtualAccountRequest: title: MWK Virtual Account description: Virtual account details for Malawi (MWK). allOf: - $ref: '#/components/schemas/BaseVirtualAccountRequest' - type: object properties: currency: type: string description: Currency code (e.g., MWK). enum: - MWK country: type: string description: Country code (e.g., MW). enum: - MW UsdVirtualAccountRequest: title: USD Virtual Account description: Virtual account details for the United States (USD). allOf: - $ref: '#/components/schemas/BaseVirtualAccountRequest' - type: object required: - gender - dateOfBirth - nationality - idType - idNumber - address - city - postalCode - company properties: currency: type: string description: Currency code. enum: - USD country: type: string description: Country code. enum: - US gender: type: string description: Gender of the representative. enum: - M - F dateOfBirth: type: string format: date description: Date of birth (YYYY-MM-DD). nationality: type: string description: 2-letter ISO country code of nationality. idType: type: string description: Type of identification provided. example: PASSPORT idNumber: type: string description: Unique ID number from the document. address: type: string description: Street address. city: type: string description: City or Town. postalCode: type: string description: Zip or Postal code. company: type: object description: Company registration details. required: - registrationNumber - registrationCountry - registrationDate properties: registrationNumber: type: string description: Business registration number. registrationCountry: type: string description: 2-letter ISO country code where the company is registered. registrationDate: type: string format: date description: Date of company registration (YYYY-MM-DD). CreateStaticVAccountSuccessResponse: type: object properties: message: type: string example: virtual account created successfully status: type: string example: success data: $ref: '#/components/schemas/StaticVirtualAccount' PayoutFailedResponse: type: object properties: message: type: string description: A human-readable error message. status: type: string example: failed required: - message - status BaseVirtualAccountRequest: type: object properties: currency: type: string description: Currency code. country: type: string description: Country code. firstName: type: string description: The customer's first name. lastName: type: string description: The customer's last name. email: type: string format: email description: The customer's email address. phoneNumber: type: string description: The customer's phone number. This must include the country code. reference: type: string description: A unique reference for the request (max 30 characters). accountName: type: string description: The desired name for the virtual account. required: - currency - country - firstName - lastName - email - phoneNumber - reference - accountName StaticVirtualAccount: type: object description: >- Details of a static (permanent) virtual account and its associated customer. properties: id: type: string format: uuid description: Unique identifier returned for the static virtual account. accountName: type: string description: Display name configured for the virtual account. reference: type: string description: Client-supplied reference used when creating the virtual account. currency: type: string description: Account currency (ISO 4217). country: type: string description: Country where the virtual account is issued (ISO 3166-1 alpha-2). status: type: string description: Lifecycle state of the virtual account (e.g. `ACTIVE`). created: type: string format: date-time description: Timestamp when the virtual account was created. customer: type: object description: Customer information captured for the account owner. properties: firstName: type: string lastName: type: string email: type: string format: email phoneNumber: type: string bvn: type: string description: 11-digit Bank Verification Number supplied during onboarding. nullable: true account: type: object description: >- Bank account details generated for payments into the virtual account. properties: name: type: string description: Account holder name returned by the provider. number: type: string description: Virtual account number end customers pay into. bankName: type: string description: Financial institution providing the account. bankCode: type: string description: Bank identifier (e.g. NIP bank code). nullable: true sortCode: type: string description: Sort code where applicable. nullable: true required: - name - number - bankName required: - id - reference - currency - country - status responses: CreateStaticVAccountSuccess: description: Static virtual account created successfully. content: application/json: schema: $ref: '#/components/schemas/CreateStaticVAccountSuccessResponse' examples: NGN_Response: summary: Nigeria (NGN) Response value: 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' USD_Response: summary: United States (USD) Response value: 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' StaticVAccountBadRequest: description: Bad Request. The provided BVN is not a valid 11-digit number. content: application/json: schema: $ref: '#/components/schemas/PayoutFailedResponse' example: message: BVN must be exactly 11 digits status: failed PayoutUnauthorized: description: Unauthorized. The provided API key is invalid or missing. content: application/json: schema: $ref: '#/components/schemas/PayoutFailedResponse' example: message: Invalid API key status: failed DynamicVAccountConflict: description: >- Conflict. Occurs if the reference has already been used in a previous request. content: application/json: schema: $ref: '#/components/schemas/PayoutFailedResponse' example: message: reference already exists status: failed PayoutInternalServerError: description: Internal Server Error. The server failed to process the request. content: application/json: schema: $ref: '#/components/schemas/PayoutFailedResponse' example: message: Server failed to process request. status: failed securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ````