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

# Simulate an inflow

> Sandbox only. Simulates a bank transfer into a `SIMULATED` sandbox virtual account. It applies the same checks as a real inflow (account expiry, and sender name when `restrictInflowToAccountName` is `true`), sends the `payment_success` or `payment_failed` webhook, and records a successful inflow so [Transaction requery](/nomba-api-reference/requery/transaction-requery) can return it by `transactionRef`. A rejected inflow returns HTTP 200 with `data.status` set to `REJECTED`. Calling it on a `LIVE` account returns 400.

> [!NOTE]
>
> Sandbox only. Works on `SIMULATED` virtual accounts; call it with base URL `https://sandbox.nomba.com`. See [Testing virtual accounts](https://developer.nomba.com/docs/api-basics/testing/virtual-accounts.md) for the full flow and the rejection codes.


## OpenAPI

````yaml post /v1/accounts/virtual/{identifier}/simulate-inflow
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/{identifier}/simulate-inflow:
    post:
      tags:
        - Virtual Accounts
      summary: Simulate an inflow
      description: >-
        Sandbox only. Simulates a bank transfer into a `SIMULATED` sandbox
        virtual account. It applies the same checks as a real inflow (account
        expiry, and sender name when `restrictInflowToAccountName` is `true`),
        sends the `payment_success` or `payment_failed` webhook, and records a
        successful inflow so [Transaction
        requery](/nomba-api-reference/requery/transaction-requery) can return it
        by `transactionRef`. A rejected inflow returns HTTP 200 with
        `data.status` set to `REJECTED`. Calling it on a `LIVE` account returns
        400.
      operationId: Simulate an inflow
      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
        - description: >-
            The account reference or account number of the `SIMULATED` virtual
            account.
          example: sandbox-va-001
          in: path
          name: identifier
          required: true
          schema:
            type: string
            example: sandbox-va-001
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateInflowRequest'
      responses:
        '200':
          description: >-
            The inflow was processed. Check `data.status` to see whether it was
            accepted.
          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/SimulateInflowResponse'
                required:
                  - code
                  - description
                  - data
        '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: []
      servers:
        - description: Sandbox
          url: https://sandbox.nomba.com
components:
  schemas:
    SimulateInflowRequest:
      type: object
      properties:
        amount:
          type: string
          description: >-
            Amount to send, in naira. Must be greater than zero. Simulated
            accounts accept any amount.
          example: '5000.00'
        senderAccountName:
          type: string
          description: >-
            The sender's account name. Checked against the virtual account name
            when `restrictInflowToAccountName` is `true`; word order doesn't
            matter.
          example: Scorsese Daniel
        senderAccountNumber:
          type: string
          description: The sender's account number. Optional.
          example: '0011223344'
        senderBankCode:
          type: string
          description: The sender's bank code. Optional.
          example: '058'
        narration:
          type: string
          description: Transfer narration. Optional.
          example: Invoice 1042
      required:
        - amount
        - senderAccountName
    SimulateInflowResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - SUCCESS
            - REJECTED
          description: Whether the inflow was accepted.
          example: SUCCESS
        responseCode:
          type: string
          description: >-
            NIP response code: `00` accepted, `07` account expired, `08` sender
            name does not match.
          example: '00'
        reason:
          type: string
          description: >-
            Why the inflow was rejected: `EXPIRED` or `NAME_MISMATCH`. Only
            present when `status` is `REJECTED`.
          example: NAME_MISMATCH
        transactionRef:
          type: string
          description: >-
            Reference of the recorded inflow. Use it with Transaction requery.
            Only present when `status` is `SUCCESS`.
          example: SANDBOX-VA-92eb15fb-56c3-4678-8dd2-faed8529f236
        sessionId:
          type: string
          description: NIP-style session ID for the simulated transfer.
          example: '999999261113102524068408167198'
        accountNumber:
          type: string
          description: The virtual account number.
          example: '0216409640'
        accountRef:
          type: string
          description: The virtual account reference.
          example: sandbox-va-001
        amount:
          type: string
          description: The amount sent.
          example: '5000.00'
    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. Both
        methods return an access token. Send it in the `Authorization` header:
        `Authorization: Bearer <access_token>`.
      scheme: bearer
      type: http
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.