> ## 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 Dynamic Virtual Account > Creates a temporary, single-use virtual account that is locked to a specific amount and expires after a set duration. ## Error responses Use this table as the source of truth for troubleshooting `POST /v1/virtual-account/dynamic`. | **Status** | **Message** | **What it means** | **How to fix** | | ---------- | --------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | 400 | `Invalid Payload` | Required fields are missing or the JSON body fails validation. | Rebuild the payload with the expected schema (`currency`, `country`, `amount`, `duration`, `reference`, etc.). | | 400 | `Duration must be an integer` | `duration` was provided as a string/float or omitted. | Supply duration as an integer number of minutes (e.g., `30`). | | 401 | `API key missing or incorrect` | Authentication header is missing, invalid, or expired. | Include the correct `x-api-key` for the environment. | | 409 | `Reference must be unique` | The `reference` value already exists from an earlier request. | Reuse the first response or generate a new reference. | | 500 | `Service temporarily unavailable` | Temporary backend outage. | Retry later with exponential backoff; contact support if it persists. | ## OpenAPI ````yaml post /v1/virtual-account/dynamic 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/dynamic: post: tags: - Virtual Account summary: Create Dynamic Virtual Account description: >- Creates a temporary, single-use virtual account that is locked to a specific amount and expires after a set duration. operationId: createDynamicVirtualAccount requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateDynamicVirtualAccountRequest' examples: NGN_Example: summary: Nigeria (NGN) Example value: currency: NGN country: NG amount: 5000 duration: 30 reference: TXN_REF_DYNAMIC_12345678 accountName: Spar Ikorodu MWK_Example: summary: Malawi (MWK) Example value: currency: MWK country: MW amount: 10000 duration: 30 reference: TXN_REF_DYNAMIC_98765432 accountName: Malawi Store responses: '200': $ref: '#/components/responses/CreateDynamicVAccountSuccess' '400': $ref: '#/components/responses/DynamicVAccountBadRequest' '401': $ref: '#/components/responses/PayoutUnauthorized' '409': $ref: '#/components/responses/DynamicVAccountConflict' '500': $ref: '#/components/responses/PayoutInternalServerError' components: schemas: CreateDynamicVirtualAccountRequest: type: object description: >- Request to create a dynamic virtual account. The required fields depend on the selected currency. oneOf: - $ref: '#/components/schemas/NgnDynamicVirtualAccountRequest' - $ref: '#/components/schemas/MwkDynamicVirtualAccountRequest' discriminator: propertyName: currency mapping: NGN: $ref: '#/components/schemas/NgnDynamicVirtualAccountRequest' MWK: $ref: '#/components/schemas/MwkDynamicVirtualAccountRequest' NgnDynamicVirtualAccountRequest: title: NGN Dynamic Virtual Account description: Dynamic virtual account details for Nigeria (NGN). allOf: - $ref: '#/components/schemas/BaseDynamicVirtualAccountRequest' - type: object properties: currency: type: string description: Currency code (NGN). enum: - NGN country: type: string description: Country code (NG). enum: - NG MwkDynamicVirtualAccountRequest: title: MWK Dynamic Virtual Account description: Dynamic virtual account details for Malawi (MWK). allOf: - $ref: '#/components/schemas/BaseDynamicVirtualAccountRequest' - type: object properties: currency: type: string description: Currency code (MWK). enum: - MWK country: type: string description: Country code (MW). enum: - MW CreateDynamicVAccountSuccessResponse: type: object properties: message: type: string example: virtual account created successfully status: type: string example: success data: $ref: '#/components/schemas/DynamicVirtualAccount' PayoutFailedResponse: type: object properties: message: type: string description: A human-readable error message. status: type: string example: failed required: - message - status BaseDynamicVirtualAccountRequest: type: object properties: currency: type: string description: Currency code. country: type: string description: Country code. amount: type: number description: The exact amount expected for the transaction. duration: type: integer description: The time in minutes for which the account will remain active. reference: type: string description: A unique reference for the transaction. accountName: type: string description: The name of the account. required: - currency - country - amount - duration - reference - accountName DynamicVirtualAccount: type: object properties: id: type: string example: 30fe4022-09da-46fb-bafa-xxxxxxxxxxxxx reference: type: string account: type: object properties: bankName: type: string sortCode: type: string nullable: true number: type: string expiryTime: type: integer format: int64 description: UNIX timestamp of when the account expires. status: type: string example: ACTIVE currency: type: string country: type: string created: type: string format: date-time responses: CreateDynamicVAccountSuccess: description: Dynamic virtual account created successfully. content: application/json: schema: $ref: '#/components/schemas/CreateDynamicVAccountSuccessResponse' DynamicVAccountBadRequest: description: >- Bad Request. Occurs if the request body is missing required fields or contains invalid data types. content: application/json: schema: $ref: '#/components/schemas/PayoutFailedResponse' example: message: Invalid request payload 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 ````