> ## Documentation Index > Fetch the complete documentation index at: https://developer.nomba.com/llms.txt > Use this file to discover all available pages before exploring further. # Create virtual account > You can use this endpoint to create a virtual account to receive payments. For a complete guide on response codes and transaction statuses, see [Response Codes](/docs/api-basics/response-codes). ## OpenAPI ````yaml post /v1/accounts/virtual openapi: 3.0.1 info: description: '' title: Vendor API version: 1.0.0 servers: - description: Production url: https://api.nomba.com - description: Sandbox url: https://sandbox.nomba.com security: [] tags: - name: Authenticate - name: Accounts - name: Virtual Accounts - name: Online Checkout - name: Charge - name: Transfers - name: Direct Debits - name: Terminals - name: Transactions - name: Airtime and Data Vending - name: Electricity Vending - name: CableTV Subscription - name: Betting Vending paths: /v1/accounts/virtual: post: tags: - Virtual Accounts summary: Create virtual account description: >- You can use this endpoint to create a virtual account to receive payments. operationId: Create virtual account parameters: - description: The parent accountId of the business. in: header name: accountId schema: type: string format: uuid example: 890022ce-bae0-45c1-9b9d-ee7872e6ca27 required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateVirtualAccountRequest' description: The request payload required to create an account required: true responses: '200': content: application/json: schema: type: object properties: code: type: string example: '00' description: Response Code description: type: string example: Success description: Response description data: $ref: '#/components/schemas/CreateVirtualAccountResponse' required: - code - description - data description: Virtual account creation successful. headers: X-Rate-Limit-Limit: description: The number of allowed requests in the current period schema: type: string example: '40' X-Rate-Limit-Remaining: description: The number of remaining requests in the current period schema: type: string example: '39' X-Rate-Limit-Window: description: The specified rate limit window schema: type: string example: 1s '400': content: application/json: schema: $ref: '#/components/schemas/RequestError' description: The request body sent by merchant did not pass the validation checks '401': content: application/json: schema: $ref: '#/components/schemas/AuthenticationError' description: >- The access_token provided to access the resource is missing or invalid. '403': content: application/json: schema: $ref: '#/components/schemas/AuthorizationError' description: The client does not have the permissions to access this resource '404': content: application/json: schema: $ref: '#/components/schemas/RecordNotFoundError' description: The record that the client is trying to access does not exist. '429': content: application/json: schema: $ref: '#/components/schemas/RateLimitError' description: >- The client has maxed out the number of calls within a time period on this resource. '500': content: application/json: schema: $ref: '#/components/schemas/ServerError' description: Downstream system error. security: - BearerAuth: [] components: schemas: CreateVirtualAccountRequest: type: object properties: accountRef: type: string description: Account reference minLength: 16 maxLength: 64 example: 1oWbJQQHLyQqqf1SwxjSpudeA21 accountName: type: string description: Account holder's name minLength: 8 maxLength: 64 example: Daniel Scorsese bvn: type: string description: Account holder's BVN. Optional. example: '12345678' nin: type: string description: |- Account holder's National Identification Number (NIN). Optional. Must be exactly 11 digits. Can be sent on its own or alongside `bvn`. If neither is sent, the BVN on the parent business account is used. minLength: 11 maxLength: 11 pattern: ^\d{11}$ example: '12345678901' expiryDate: type: string description: Account expiry date in UTC. Optional. ⚠️Be careful with this. example: '2026-01-30 12:15:00' expectedAmount: type: number format: double description: Amount the account can receive. Optional. example: '200.00' restrictInflowToAccountName: type: boolean description: >- When set to true, Nomba will reject any inflow to the virtual account whose sender name does not match the virtual account name. The order of names does not matter—for example, a VA name of 'John Doe Naomi' would match sender names like 'Doe John Naomi' or 'Naomi Doe John', since different banks may arrange names differently. A `payment_failed` webhook event is sent to notify the merchant that the inflow was rejected. The rejected inflow is reversed back to the sender according to the sending bank's policy. Optional. example: true required: - accountRef - accountName CreateVirtualAccountResponse: type: object properties: createdAt: type: string description: Creation timestamp format: date-time example: '2023-09-04T07:09:06.900Z' accountHolderId: type: string description: Account holder ID minLength: 36 maxLength: 36 example: 01a10aeb-d989-460a-bbde-9842f2b4320f accountRef: type: string description: Account reference minLength: 16 maxLength: 64 example: 1oWbJQQHLyQqqf1SwxjSpudeA21 bvn: type: string description: Bank Verification Number (BVN) minLength: 11 maxLength: 11 example: '12234412345' identifierType: type: string description: >- The type of identifier the virtual account was created against. Omitted when the account has no identifier. enum: - BVN - NIN - BVN_AND_NIN example: BVN accountName: type: string description: Account holder's name minLength: 8 maxLength: 64 example: Daniel Scorsese bankName: type: string description: Bank name example: Nombank MFB bankAccountNumber: type: string description: Bank account number example: '9391076543' bankAccountName: type: string description: Bank account holder name example: Nomba/Ifeoluwa Adeboye currency: type: string description: Currency code minLength: 3 maxLength: 3 enum: - NGN example: NGN callbackUrl: type: string description: Callback url format: url example: https://webhook.site/98ef100f-5adc-4434-800a-0808h60bd8d7 expired: type: boolean description: Successfully updated example: true restrictInflowToAccountName: type: boolean description: >- Indicates whether inflow restriction by account name is enabled. When true, the virtual account was successfully created with name restriction, meaning inflows will only be accepted if the sender's name matches the account name. example: true required: - createdAt - accountId - accountHolderId - accountRef - bvn - status - type - accountName - banks - currency RequestError: type: object description: Request Error response. properties: code: type: string description: API error code. example: '400' description: type: string description: Additional details about the error. example: Request failed. AuthenticationError: type: object description: Authentication Error response. properties: code: type: string description: API error code. example: '401' description: type: string description: Additional details about the error. example: Unauthorized AuthorizationError: type: object description: Permissions error response. properties: code: type: string description: API error code. example: '403' description: type: string description: Additional details about the error. example: Forbidden RecordNotFoundError: type: object description: Record-Not-Found error response. properties: code: type: string description: API error code. example: '404' description: type: string description: Additional details about the error. example: Record not found RateLimitError: type: object description: Rate-limit error response. properties: code: type: string description: API error code. example: '429' description: type: string description: Additional details about the error. example: Too many requests ServerError: type: object description: Server error response. properties: code: type: string description: API error code. example: '500' description: type: string description: Additional details about the error. example: Server error securitySchemes: BearerAuth: description: >- Nomba authenticates API calls with [OAuth2 HTTP bearer tokens](http://tools.ietf.org/html/rfc6750). There are two methods of authentication; [Client-Credentials method](https://www.rfc-editor.org/rfc/rfc6749) and [PKCE (Proof Key for Code Exchange)](https://www.rfc-editor.org/rfc/rfc7636) method. In each of the methods, You will get an `ACCESS_TOKEN`. You need to use an `"Authorization"` HTTP header to provide your `ACCESS_TOKEN`. For example: `Authorization: {ACCESS_TOKEN}`. scheme: bearer type: http bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.