> ## 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.

# Simulate Virtual Account Transfer

> Sandbox only; returns 403 in production. Credits a bank transfer into one of your sandbox virtual accounts, the way the account provider's deposit notification would, so balances and your transaction webhook behave as in production. Pass the account number; for an account created with an `amount` (a one-time account), also pass the `reference` it was issued with. The deposit is reported by the transaction webhook.

<Note>
  **Sandbox only.** Returns `403` in production.
</Note>

Credits a bank transfer into one of your sandbox virtual accounts, exactly as the underlying provider's deposit notification would in production. Balances and the `TRANSACTION.UPDATED` webhook behave the same.

Sandbox virtual accounts receive no money on their own, so use this endpoint whenever you want to test what happens after a customer funds one.

## Choosing the account

* **Reusable virtual account** (created without `amount`): pass the `accountNumber` and `amount` to credit.
* **One-time virtual account** (created with `amount`): pass the same `reference` the account was issued with, in addition to `accountNumber` and `amount`.

## Controlling the outcome

`outcome` defaults to `success`. Pass `"outcome": "failed"` to simulate a failed inflow.

The deposit lands as a transaction and is reported by webhook. See the [Sandbox testing guide](/guides/testing-in-sandbox) for how virtual accounts fit into the broader sandbox model.


## OpenAPI

````yaml POST /api/v1/payment-method/virtual-account/simulate-transfer
openapi: 3.1.0
info:
  title: Afriex Business API
  version: 1.0.13
  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.


    ## Testing in sandbox


    Send requests to `https://sandbox.api.afriex.com` with a sandbox API key.

    No real money moves. Payouts, mobile money and card deposits, and virtual

    accounts can be tested in every currency your business supports.


    **When transactions complete.** A sandbox deposit or payout completes on

    its own about 5 minutes after it is created, and your webhook receives the

    final status, exactly as in production. To complete one sooner:


    - Include `SIMULATE_INSTANT` anywhere in `meta.reference` when you create
      it, and it completes in about 30 seconds.
    - Or call `POST /api/v1/transaction/{transactionId}/simulate` with
      `{"outcome": "success"}` or `{"outcome": "failed"}` to complete it now.

    **Choosing an outcome.** The last four digits of the bank account number,

    the mobile money phone number or the card number decide what happens:


    | Ends in | Payout | Mobile money deposit | Card deposit |

    | --- | --- | --- | --- |

    | anything else | Succeeds | Succeeds | Succeeds |

    | `0001` | Fails; your balance is refunded | Fails | Fails |

    | `0002` | Succeeds | Waits for a one-time password (see below) | Succeeds |

    | `0003` | Stays pending until you call `/simulate` | Stays pending until
    you call `/simulate` | Stays pending until you call `/simulate` |

    | `0004` | Account name lookup (`GET /api/v1/payment-method/resolve`) fails
    | Succeeds | Succeeds |

    | `0005` | Declined immediately | Declined immediately | Declined
    immediately |


    A phone number must still be a valid mobile number for its country, so keep

    the country prefix and change only the last digits, for example

    `+254712340002` in Kenya. Account name lookups return `Sandbox Test
    Account`.


    **One-time passwords.** A mobile money deposit from a wallet ending in

    `0002` returns `CUSTOMER_ACTION_REQUIRED`. Complete it with

    `POST /api/v1/transaction/{transactionId}/authorize` and the OTP `123456`;

    any other OTP returns `OTP_INCORRECT`. The deposit then completes as above.


    **Virtual accounts.** Sandbox virtual accounts receive no money on their

    own. Pay into one with

    `POST /api/v1/payment-method/virtual-account/simulate-transfer`.


    **Cards.** Collect the card as you would in production, using a test card

    number whose last four digits choose the outcome.


    **Balances and webhooks.** Fund your sandbox balance with

    `POST /api/v1/org/balance/topup`, and send yourself a sample webhook with

    `POST /api/v1/webhooks/trigger`.
  termsOfService: https://www.afriex.com/terms-and-condition
  contact:
    name: Afriex API Support
    email: support@afriex.com
    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.
  - name: Payment Batches
    description: >-
      Manage payment batches, their recipients and their runs.


      Where payload signing is enabled for your business, sign the JSON of the
      request body for POST and PATCH routes that take one. For GET routes with
      `page` and `limit`, and for the withdraw route, sign the query parameters
      as the server reads them, with defaults applied: a list call with no
      parameters signs `{"limit":100,"page":0}` and a withdraw with no
      `sessionId` signs `{}`. For the remaining routes (get, delete and
      remove-recipient) sign the path parameters, e.g. `{"batchId":"..."}`.
paths:
  /api/v1/payment-method/virtual-account/simulate-transfer:
    parameters:
      - $ref: '#/components/parameters/x-api-version'
    post:
      tags:
        - Payment Methods
      summary: Simulate a transfer into a sandbox virtual account
      description: >-
        Sandbox only; returns 403 in production. Credits a bank transfer into
        one of your sandbox virtual accounts, the way the account provider's
        deposit notification would, so balances and your transaction webhook
        behave as in production. Pass the account number; for an account created
        with an `amount` (a one-time account), also pass the `reference` it was
        issued with. The deposit is reported by the transaction webhook.
      operationId: simulateVirtualAccountTransfer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                accountNumber:
                  type: string
                  description: The virtual account number to pay into.
                amount:
                  type: number
                  description: The amount transferred.
                currency:
                  type: string
                  description: The account's currency.
                reference:
                  type: string
                  description: >-
                    The reference a one-time (amount-bound) account was issued
                    with. Not needed for a reusable account.
                outcome:
                  type: string
                  description: Defaults to `success`.
                  enum:
                    - success
                    - failed
              required:
                - accountNumber
                - amount
                - currency
            examples:
              transfer:
                summary: Pay 5,000 NGN into a sandbox account
                value:
                  accountNumber: '4821930275'
                  amount: 5000
                  currency: NGN
      responses:
        '202':
          description: Accepted. The reference of the new deposit.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      reference:
                        type: string
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Not available in production.
        '404':
          description: No sandbox virtual account with that number for your business.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    x-api-version:
      name: x-api-version
      in: header
      required: false
      description: >-
        API version in ISO 8601 format. The only supported version is
        `2026-05-18`, which is also the default when the header is omitted. Any
        other value is rejected with a `400 Bad Request`.
      schema:
        type: string
  schemas:
    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'
    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 is rejected with a `401 Unauthorized` response, the same

        response an unrecognised, malformed, revoked or disabled key returns.
        The API

        does not distinguish the two cases on the wire.

        Manage your keys and their permissions under **Developer → API keys**

        in the dashboard.


        The permission each endpoint requires is below. Where several are

        listed, any one of them is enough. Keys created before permissions

        existed carry none and keep access to every endpoint.


        | Endpoint | Permission |

        | --- | --- |

        | `GET /customer`, `GET /customer/{customerId}` | `CUSTOMER.READ` |

        | `POST /customer` | `CUSTOMER.CREATE` |

        | `PATCH /customer/{customerId}`, `PATCH /customer/{customerId}/kyc`,
        `POST /customer/{customerId}/verify` | `CUSTOMER.UPDATE` |

        | `DELETE /customer/{customerId}` | `CUSTOMER.DELETE` |

        | `GET /payment-method`, `GET /payment-method/{paymentMethodId}`, `GET
        /payment-method/institution`, `GET /payment-method/institution/codes`,
        `GET /payment-method/resolve`, `GET /payment-method/virtual-account`,
        `GET /payment-method/pool-account` | `PAYMENT_METHOD.READ` |

        | `POST /payment-method`, `DELETE /payment-method/{paymentMethodId}`,
        `POST /payment-method/virtual-account`, `GET
        /payment-method/crypto-wallet`, `POST
        /payment-method/virtual-account/simulate-transfer` (sandbox only) |
        `PAYMENT_METHOD.CREATE` |

        | `POST /transaction` | `TRANSACTION.DEPOSIT.CREATE`,
        `TRANSACTION.WITHDRAW.CREATE` or `TRANSACTION.SWAP.CREATE` |

        | `POST /transaction/{transactionId}/authorize`, `POST
        /transaction/pool-account` | `TRANSACTION.DEPOSIT.CREATE` |

        | `POST /transaction/{transactionId}/simulate` (sandbox only) |
        `TRANSACTION.DEPOSIT.CREATE` or `TRANSACTION.WITHDRAW.CREATE` |

        | `GET /transaction`, `GET /transaction/{transactionId}`, `GET
        /transaction/{transactionId}/advice` | `TRANSACTION.HISTORY.READ` |

        | `GET /org/balance`, `GET /org/rates` | `WALLET.BALANCES.READ` |

        | `POST /media/url` | `PAYMENT_METHOD.CREATE` |

        | `POST /sme-registration` | `COMPLIANCE.KYB.SUBMIT` |

        | `GET /sme-registration/status` | `COMPLIANCE.KYB.READ` |

        | `POST /checkout-session` | `CHECKOUT_LINK.CREATE` |

        | `GET /payment-batch`, `GET /payment-batch/{batchId}`, `GET
        /payment-batch/{batchId}/recipients` | `PAYMENT_METHOD.READ` |

        | `POST /payment-batch`, `PATCH /payment-batch/{batchId}`, `DELETE
        /payment-batch/{batchId}`, `POST /payment-batch/{batchId}/recipients`,
        `POST /payment-batch/{batchId}/recipients/bulk`, `PATCH
        /payment-batch/{batchId}/recipients/{recipientId}`, `DELETE
        /payment-batch/{batchId}/recipients/{recipientId}` |
        `PAYMENT_METHOD.CREATE` |

        | `POST /payment-batch/{batchId}/withdraw` |
        `TRANSACTION.WITHDRAW.CREATE` |

        | `GET /payment-batch/{batchId}/sessions` | `TRANSACTION.HISTORY.READ` |

        | `POST /org/balance/topup`, `POST /webhooks/trigger` | None; any valid
        key |

````