> ## Documentation Index > Fetch the complete documentation index at: https://docs.afriex.com/llms.txt > Use this file to discover all available pages before exploring further. # List Virtual Accounts > Returns every active virtual account for the resolved customer-or-owner and currency. Read-only: when no virtual account exists, the response is **200** with `data: []`. Pass `customerId` to scope the list to a specific end-user; omit it to list the virtual accounts belonging to the business owner. **Breaking change from earlier versions:** the previous endpoint returned a single virtual account and would create one on the fly when absent. It now returns a list and never creates. The create path lives at `POST /api/v1/payment-method/virtual-account`; the `POOL_ACCOUNT` variant has moved to `GET /api/v1/payment-method/pool-account`. Returns every active virtual account for the resolved customer-or-owner and currency. The endpoint is read-only: when no virtual account exists, you get a `200` response with `data: []` rather than a `404`. Pass `customerId` to scope the list to a specific end-user. Omit it to list virtual accounts that belong to the business owner. **Important:** Virtual accounts are **only active in production** and do **not work on staging/dev**. Want to see virtual accounts in action? Learn how to build payment links using them: [https://dev.to/afriex/send-a-link-get-paid-building-payment-links-with-afriex-13ak](https://dev.to/afriex/send-a-link-get-paid-building-payment-links-with-afriex-13ak) *** ## Breaking change from earlier versions Previously this endpoint returned a single virtual account and would create one on the fly when none existed. It now returns a list and never creates. The behaviour has been split into three explicit endpoints: | Endpoint | What it does | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET /api/v1/payment-method/virtual-account` | Lists existing virtual accounts (this page). Read-only. | | `POST /api/v1/payment-method/virtual-account` | Creates a new virtual account. See [Create Virtual Account](/api-reference/endpoint/payment-methods/virtual-account-create). | | `GET /api/v1/payment-method/pool-account` | Returns the business pool account for a country. Use the `reference` on the response to reconcile incoming deposits. See [Get Pool Account](/api-reference/endpoint/payment-methods/pool-account). | If you were relying on the get-or-create behaviour, call `GET` first; when `data` is empty, follow up with `POST` to create one. *** ## Virtual accounts are for end customers Virtual accounts are designed for your **customers as end users**, meaning the people your business is acting on behalf of. Each virtual account is linked to a `customerId` (or to the business owner if no `customerId` is provided). Payments received into a virtual account are attributed to the associated customer in your Afriex system. Make sure you have created a Customer record before listing or creating virtual accounts for that person. See [Create Customer](/api-reference/endpoint/customers/create). ## OpenAPI ````yaml GET /api/v1/payment-method/virtual-account openapi: 3.1.0 info: title: Afriex Business API version: 1.0.8 description: >- Welcome to the Afriex Business API. This API allows you to manage customers, process payments, handle payouts, and receive real-time notifications via webhooks. For detailed guidance on authentication, pagination, error handling, and webhooks, please refer to the [dedicated guides](https://docs.afriex.com) in the top bar. The guide provides a step-by-step instructions to help you integrate seamlessly. termsOfService: https://www.afriex.com/terms-and-condition contact: name: Afriex API Support email: eng@afriex.co url: https://docs.afriex.com license: name: Proprietary url: https://www.afriex.com/terms-and-condition servers: - url: https://sandbox.api.afriex.com description: Staging Base URL - url: https://api.afriex.com description: Production Base URL security: - ApiKey: [] tags: - name: Customers description: Create and manage your customers. - name: Payment Methods description: Register and resolve customer payout and collection methods. - name: Transactions description: Create and track deposits, withdrawals, and swaps. - name: Balance description: View and top up your business wallet balances. - name: Rates description: Fetch real-time exchange rates. - name: Checkout Sessions description: Create hosted checkout sessions. - name: Webhooks description: Webhook event payloads and sandbox webhook testing. - name: Media description: Generate presigned URLs for secure file uploads. paths: /api/v1/payment-method/virtual-account: parameters: - $ref: '#/components/parameters/x-api-version' get: tags: - Payment Methods summary: List existing virtual accounts description: | Returns every active virtual account for the resolved customer-or-owner and currency. Read-only: when no virtual account exists, the response is **200** with `data: []`. Pass `customerId` to scope the list to a specific end-user; omit it to list the virtual accounts belonging to the business owner. **Breaking change from earlier versions:** the previous endpoint returned a single virtual account and would create one on the fly when absent. It now returns a list and never creates. The create path lives at `POST /api/v1/payment-method/virtual-account`; the `POOL_ACCOUNT` variant has moved to `GET /api/v1/payment-method/pool-account`. operationId: listVirtualAccounts parameters: - name: currency in: query description: The 3-letter ISO 4217 currency code for the virtual account required: true schema: type: string enum: - USD - NGN - GBP - EUR - name: customerId in: query description: | Optional customer ID. When supplied, the lookup is scoped to that customer. When omitted, it resolves to the business owner. required: false schema: type: string - name: country in: query description: Optional ISO 3166-1 alpha-2 country code. required: false schema: type: string - name: amount in: query description: Optional positive amount. required: false schema: type: number - name: reference in: query description: Optional merchant-supplied reference. required: false schema: type: string responses: '200': description: Virtual accounts retrieved successfully (possibly empty list). content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/PaymentMethod' total: type: integer description: Number of items in `data`. page: type: integer description: >- Page index. Currently always `0`, the endpoint returns all matching VAs in a single response. examples: twoNgnAccounts: summary: Two NGN virtual accounts for a customer value: data: - paymentMethodId: 690cc5bbe2a1143ff6070119 channel: VIRTUAL_BANK_ACCOUNT customerId: 68e6717848e1f632e9686460 institution: institutionName: FIDELITY BANK accountName: Lily New accountNumber: '3820404958' countryCode: NG - paymentMethodId: 690cc5bbe2a1143ff607011a channel: VIRTUAL_BANK_ACCOUNT customerId: 68e6717848e1f632e9686460 institution: institutionName: FIDELITY BANK accountName: Lily New (Sales) accountNumber: '3820404971' countryCode: NG total: 2 page: 0 noAccounts: summary: No virtual accounts exist for this customer/currency value: data: [] total: 0 page: 0 '400': description: Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingCurrency: summary: Missing currency parameter value: code: VALIDATION_ERROR error: 'Failed to parse request. Issues: ''currency'' is required' details: {} invalidCurrency: summary: Unsupported currency code value: code: VALIDATION_ERROR error: >- Failed to parse request. Issues: 'currency' must be one of [USD, NGN, GBP, EUR] details: {} '401': description: Unauthorized - Invalid business API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: Missing API key value: code: AUTHENTICATION_ERROR error: Authorization header is missing details: {} invalidApiKey: summary: Invalid API key value: code: AUTHENTICATION_ERROR error: Invalid authorization header details: {} '500': description: Server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: serverError: summary: Unexpected server error value: code: INTERNAL_SERVER_ERROR error: It's not you, it's us, please reach out to support details: {} x-codeSamples: - lang: TypeScript label: Afriex SDK source: | const response = await afriex.paymentMethods.listVirtualAccounts({ customerId: "customer-id", currency: "USD", }); components: parameters: x-api-version: name: x-api-version in: header required: false description: >- API version in ISO 8601 format (e.g. 2025-12-28). Defaults to latest stable. schema: type: string schemas: PaymentMethod: type: object description: >- A payment method. Empty fields are omitted. Account-shaped channels (BANK_ACCOUNT, MOBILE_MONEY, SWIFT, etc.) populate accountName, accountNumber, and institution; the CARD channel instead populates last4, brand, expiration, and cardName. properties: paymentMethodId: type: string description: The unique identifier for the payment method. customerId: $ref: '#/components/schemas/customerId' reference: type: string description: Identifier to reconcile incoming deposits against. institution: $ref: '#/components/schemas/PaymentMethodInstitution' transaction: $ref: '#/components/schemas/PaymentMethodTransaction' recipient: $ref: '#/components/schemas/PaymentMethodRecipient' channel: type: string enum: - BANK_ACCOUNT - MOBILE_MONEY - SWIFT - INTERAC - UPI - WE_CHAT - ALIPAY - CARD - CRYPTO - VIRTUAL_BANK_ACCOUNT - POOL_ACCOUNT - ACH_BANK_ACCOUNT - PAYBILL_TILL - RFP - VIRTUAL_CARD description: The payment method channel. countryCode: type: string description: The ISO 3166-1 alpha-2 country code. currency: type: string description: >- The payment method's currency (ISO 4217). Use this instead of inferring currency from countryCode, which is ambiguous (e.g. a USD account in a non-US country). capabilities: type: array items: type: string description: >- The operations this payment method is enabled for (e.g. DEPOSIT, WITHDRAW). Use it to select deposit-capable vs withdraw-capable methods. Also filterable via the `capabilities` query parameter. accountName: type: string description: Name of the account holder. Present for account-shaped channels. accountNumber: type: string description: Account number. Present for account-shaped channels. routingNumber: type: string description: >- Bank routing number. Present for account-shaped channels that carry one (e.g. ACH bank accounts). status: type: string enum: - active - pending - deleted - expired - blocked description: Lifecycle status of the payment method. last4: type: string description: Last 4 digits of the card. CARD channel only. brand: type: string enum: - Visa - MasterCard - Discover - American Express - JCB - Diners Club - Eftpos Australia - UnionPay - Unknown description: Card brand. CARD channel only. expiration: type: object description: Card expiration. CARD channel only. properties: month: type: integer year: type: integer cardName: type: string description: Name on the card. CARD channel only. expiresInMinutes: type: integer description: Minutes until a dynamic virtual account expires, when applicable. amount: type: number description: Requested amount for a dynamic virtual account, when applicable. extra: type: object description: Additional channel-specific properties. additionalProperties: true meta: type: object description: Optional meta data you attached to the payment method. ErrorResponse: type: object properties: code: type: string description: Machine-readable error code. error: type: string description: Human-readable error message. details: $ref: '#/components/schemas/ErrorDetails' customerId: type: string description: The unique identifier of the customer. PaymentMethodInstitution: type: object properties: institutionId: type: string description: >- The unique identifier of the bank or mobile money provider if required. institutionName: type: string description: The name of the bank or mobile money provider if required. institutionCode: type: string description: The code of the bank or mobile money provider. institutionAddress: type: string description: The address of the bank or mobile money provider if required. correspondentBankName: type: string description: >- The correspondent (intermediary) bank name. Mandatory for USD (SWIFT) payout payment methods; required to produce settlement advices/invoices. correspondentBankAccountNumber: type: string description: >- The correspondent (intermediary) bank account number. Mandatory for USD (SWIFT) payout payment methods; required to produce settlement advices/invoices. PaymentMethodTransaction: type: object properties: transactionInvoice: type: string description: >- The invoice filename (S3 object key) for the transaction, as returned by the media upload endpoint. transactionNarration: type: string description: The optional reason for the transaction. PaymentMethodRecipient: type: object properties: recipientEmail: type: string format: email description: The email address of the recipient if needed. recipientPhone: type: string description: The phone number of the recipient in E.164 format. recipientAddress: type: string description: The address of the recipient if needed. recipientName: type: string description: The name of the recipient if needed. ErrorDetails: type: object properties: errorMessage: type: string description: Detailed/technical error message. friendlyMessage: type: string description: User-facing error message safe to display. data: type: object description: >- Optional caller-safe context for the error. On a customer-create uniqueness conflict (EMAIL_ALREADY_EXISTS / PHONE_NUMBER_ALREADY_EXISTS) this carries the existing customer's id, so you can adopt it without a follow-up lookup. properties: customerId: type: string description: Id of the existing customer (on a create conflict). securitySchemes: ApiKey: type: apiKey in: header name: x-api-key description: >- Static business API key issued from the dashboard. A business can provision **multiple API keys**, each scoped to a configurable set of **permissions** (e.g. read transactions, create deposits, etc). Permissions are chosen per key at creation time in the dashboard and may be revoked by deleting the key. Requests made with a key that does not include the permission required by the target endpoint will be rejected with a `403 Forbidden` response; an unrecognised, malformed or revoked key returns `401 Unauthorized`. Manage your keys and their permissions under **Developer → API keys** in the dashboard. ````