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

# Make airtime purchases via parent account (v2)

> You can use this endpoint to make airtime purchases via parent account.

<Warning>
  Always requery the transaction using [Fetch a single transaction on the parent account](/nomba-api-reference/requery/fetch-a-single-transaction-on-the-parent-account) to confirm its final status before issuing a refund.
</Warning>

<Note>
  The `code` field in the response reflects the HTTP status code of the response. For example, `200` means the request completed successfully, and `201` means it was accepted and is still being processed.
</Note>


## OpenAPI

````yaml post /v2/bill/topup
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:
  /v2/bill/topup:
    post:
      tags:
        - Airtime and Data Vending
      summary: Make airtime purchases via parent account
      description: You can use this endpoint to make airtime purchases via parent account.
      operationId: Make airtime purchases via parent account v2
      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/AirtimePurchaseRequest'
        description: The request payload required to make airtime purchases
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: >-
                      Response code. This reflects the HTTP status code of the
                      response, e.g. `200` when the request completed
                      successfully and `201` when it was accepted and is still
                      being processed.
                    example: '200'
                    enum:
                      - '200'
                      - '201'
                      - '400'
                      - '401'
                      - '403'
                      - '429'
                      - '500'
                  description:
                    type: string
                    example: SUCCESS
                    description: Response description
                  message:
                    type: string
                    description: Response message
                    example: Transaction completed Successfully
                  status:
                    type: boolean
                    description: Whether the request was successful
                    example: true
                  data:
                    $ref: '#/components/schemas/AirtimePurchaseV2Response'
                required:
                  - code
                  - description
                  - data
              example:
                code: '200'
                description: SUCCESS
                message: Transaction completed Successfully
                status: true
                data:
                  id: API-TOPUP-A6950-8c060b7c-4155-4e33-a846-101b49229c33
                  status: SUCCESS
                  type: topup
                  amount: 100
                  source: api
                  sourceUserId: null
                  customerBillerId: '08123456788'
                  productId: '62130'
                  meta:
                    api_rrn: '260926204701'
                    rrn: '260926204701'
                    api_account_id: 0167288-d989-460a-bbde-9842f2b4320f
                    api_client_id: 2167288-d989-460a-bbde-9842f2b4320f
                    user_id: 0167288-d989-460a-bbde-9842f2b4320f
                    merchantTxRef: REF-29-07-2026-12
                    allowDuplicate: true
                    sender_name: John Doe
                    idempotentKey: 0167288-d989-460a-bbde-9842f2b4320f_REF-29-07-2026-12
                    pos_withdrawal_id: 0167288-d989-460a-bbde-9842f2b4320f_REF-29-07-2026-12
                    userName: John Doe
                    isCorporate: 'true'
                    currency: NGN
                    hooksEligible: 'true'
                    isSubscribedToSavingsService: false
                    isSubscribedToLoanService: false
                    txnAlertEligible: true
                    banking_entity_id: 189585760
                    banking_entity_user_id: 188595905
                    banking_entity_type: CORPORATE
                    transactionCategory: Bills & Utility
                    network: mtn
                    subscriberNumber: '08123456788'
                    amount_charged: '100.0'
                    wallet_balance: '610.55'
                    wallet_currency: NGN
                    agent_commission: '2.0'
                    gatewayMessage: Success
                    billingServiceTransactionId: 6ab821352669ea6eac2bb2ba
                    billingServiceResponse: SUCCESS
                    income: '0.5'
                    paymentFee: 0
                    tx_revenue: '2.5'
                    phoneNumber: '08123456788'
                  userId: null
                  timeCreated: '2026-09-26T19:47:01.514+00:00'
          description: OK - your request was 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
        '201':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: >-
                      Response code. This reflects the HTTP status code of the
                      response, e.g. `200` when the request completed
                      successfully and `201` when it was accepted and is still
                      being processed.
                    example: '201'
                    enum:
                      - '200'
                      - '201'
                      - '400'
                      - '401'
                      - '403'
                      - '429'
                      - '500'
                  description:
                    type: string
                    description: Response description
                    example: PROCESSING
                  message:
                    type: string
                    description: Response message
                    example: Success
                  status:
                    type: boolean
                    description: Whether the request was successful
                    example: true
                  data:
                    $ref: '#/components/schemas/AirtimePurchaseV2Response'
                required:
                  - code
                  - description
                  - data
              example:
                code: '201'
                description: PROCESSING
                message: Success
                status: true
                data:
                  id: API-TOPUP-A6950-8c060b7c-4155-4e33-a846-101b49229c33
                  status: PENDING_BILLING
                  type: topup
                  amount: 100
                  source: api
                  sourceUserId: null
                  customerBillerId: '08123456788'
                  productId: '62130'
                  meta:
                    api_rrn: '260926204701'
                    rrn: '260926204701'
                    api_account_id: 0167288-d989-460a-bbde-9842f2b4320f
                    api_client_id: 2167288-d989-460a-bbde-9842f2b4320f
                    user_id: 0167288-d989-460a-bbde-9842f2b4320f
                    merchantTxRef: REF-29-07-2026-12
                    allowDuplicate: true
                    sender_name: John Doe
                    idempotentKey: 0167288-d989-460a-bbde-9842f2b4320f_REF-29-07-2026-12
                    pos_withdrawal_id: 0167288-d989-460a-bbde-9842f2b4320f_REF-29-07-2026-12
                    userName: John Doe
                    isCorporate: 'true'
                    currency: NGN
                    hooksEligible: 'true'
                    isSubscribedToSavingsService: false
                    isSubscribedToLoanService: false
                    txnAlertEligible: true
                    banking_entity_id: 189585760
                    banking_entity_user_id: 188595905
                    banking_entity_type: CORPORATE
                    transactionCategory: Bills & Utility
                    network: mtn
                    subscriberNumber: '08123456788'
                    amount_charged: '100.0'
                    wallet_balance: '610.55'
                    wallet_currency: NGN
                    phoneNumber: '08123456788'
                  userId: null
                  timeCreated: '2026-09-26T19:47:01.514+00:00'
          description: >-
            Created - your request was accepted and is being processed.
            `data.status` is `PENDING_BILLING`; listen for webhook notifications
            or requery the transaction for the final status.
          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.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Resource not available
      security:
        - BearerAuth: []
components:
  schemas:
    AirtimePurchaseRequest:
      type: object
      properties:
        amount:
          type: number
          format: double
          description: The airtime amount to be purchased
          example: 200
        phoneNumber:
          type: string
          description: Recipient phone number
          minLength: 11
          maxLength: 13
          example: '08055441122'
        network:
          type: string
          description: >-
            Recipient network (telco). It can also come as lowercased values
            e.g. glo, mtn etc.
          minLength: 3
          enum:
            - GLO
            - MTN
            - 9MOBILE
            - AIRTEL
          example: GLO
        merchantTxRef:
          type: string
          description: |-
            Merchant Transaction Identifier reference (Unique to merchant) 
             
             This is an idempotency key and must be unique per transaction.
          example: 3bvwhibh38220dsjakTwvb
        senderName:
          type: string
          description: A name to describe the sender of the airtime
          example: John Doe
      required:
        - amount
        - phoneNumber
        - network
        - merchantTxRef
    AirtimePurchaseV2Response:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the airtime transaction
          example: API-TOPUP-A6950-8c060b7c-4155-4e33-a846-101b49229c33
        status:
          type: string
          description: >-
            Status of the transaction. `SUCCESS` (HTTP 200) means the purchase
            completed; `PENDING_BILLING` (HTTP 201) means it is still being
            processed
          example: SUCCESS
        type:
          type: string
          description: Transaction type
          example: topup
        amount:
          type: number
          format: double
          description: Airtime amount purchased
          example: 100
        source:
          type: string
          description: Channel through which the transaction was initiated
          example: api
        sourceUserId:
          type: string
          description: Identifier of the source user, if any
          nullable: true
        customerBillerId:
          type: string
          description: Phone number credited with the airtime
          example: '08123456788'
        productId:
          type: string
          description: Product identifier for the airtime purchase
          example: '62130'
        meta:
          type: object
          description: Additional transaction metadata
          additionalProperties: true
          example:
            api_rrn: '260926204701'
            rrn: '260926204701'
            api_account_id: 0167288-d989-460a-bbde-9842f2b4320f
            api_client_id: 2167288-d989-460a-bbde-9842f2b4320f
            user_id: 0167288-d989-460a-bbde-9842f2b4320f
            merchantTxRef: REF-29-07-2026-12
            allowDuplicate: true
            sender_name: John Doe
            idempotentKey: 0167288-d989-460a-bbde-9842f2b4320f_REF-29-07-2026-12
            pos_withdrawal_id: 0167288-d989-460a-bbde-9842f2b4320f_REF-29-07-2026-12
            userName: John Doe
            isCorporate: 'true'
            currency: NGN
            hooksEligible: 'true'
            isSubscribedToSavingsService: false
            isSubscribedToLoanService: false
            txnAlertEligible: true
            banking_entity_id: 189585760
            banking_entity_user_id: 188595905
            banking_entity_type: CORPORATE
            transactionCategory: Bills & Utility
            network: mtn
            subscriberNumber: '08123456788'
            amount_charged: '100.0'
            wallet_balance: '610.55'
            wallet_currency: NGN
            agent_commission: '2.0'
            gatewayMessage: Success
            billingServiceTransactionId: 6ab821352669ea6eac2bb2ba
            billingServiceResponse: SUCCESS
            income: '0.5'
            paymentFee: 0
            tx_revenue: '2.5'
            phoneNumber: '08123456788'
        userId:
          type: string
          description: Identifier of the user, if any
          nullable: true
        timeCreated:
          type: string
          description: Time the transaction was created
          format: date-time
          example: '2026-09-26T19:47:01.514+00:00'
      required:
        - id
        - status
        - type
        - amount
        - timeCreated
    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

````