> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepanel.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Move airtime from a user's line to your SIM

> Sends airtime from the session's MTN line to your connected MTN SIM. Credit the user only when `status` is `success` (or when you receive the `airtime_cash.transfer.success` webhook). The user's 4-digit MTN transfer PIN must be sent with every request; it is never stored. Repeating a `reference` never sends twice: you get the original result back.




## OpenAPI

````yaml /openapi.yaml post /airtime-cash/transfers
openapi: 3.0.3
info:
  title: OnePanel API
  version: 1.0.0
  description: API for OnePanel data vending and transaction management.
servers:
  - url: https://api.onepanel.ng/api/v1
    description: Production
security: []
tags:
  - name: Catalog
  - name: Purchases
  - name: Transactions
  - name: Account
  - name: Airtime Cash
paths:
  /airtime-cash/transfers:
    post:
      tags:
        - Airtime Cash
      summary: Move airtime from a user's line to your SIM
      description: >
        Sends airtime from the session's MTN line to your connected MTN SIM.
        Credit the user only when `status` is `success` (or when you receive the
        `airtime_cash.transfer.success` webhook). The user's 4-digit MTN
        transfer PIN must be sent with every request; it is never stored.
        Repeating a `reference` never sends twice: you get the original result
        back.
      operationId: createAirtimeCashTransfer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferRequest'
            example:
              session_id: 3f1c2a9e-5b1d-4f0e-9a58-1d2b7c6e8a10
              amount: 1000
              pin: '1234'
              reference: order-2026-0001
      responses:
        '200':
          description: Airtime received (`status` is `success`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transfer'
        '202':
          description: >
            Result not confirmed yet (`status` is `pending` or `unknown`). Do
            not credit the user and do not resend; check `GET
            /airtime-cash/transfers/{reference}`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transfer'
        '409':
          description: >
            The session is not usable. `session_status` is `reauth_required` or
            `expired`: ask the user for a new OTP. Also returned when you have
            no connected MTN SIM to receive airtime.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >
            Refused. Either MTN rejected the transfer (`status` is `failed`,
            `message` is MTN's own reply, for example a wrong PIN), or the
            amount is over one of your limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transfer'
        '429':
          description: Too many failed transfers on this session in the last hour.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    TransferRequest:
      type: object
      required:
        - session_id
        - amount
        - pin
        - reference
      properties:
        session_id:
          type: string
        amount:
          type: integer
          description: Whole naira. Minimum 50.
          example: 1000
        pin:
          type: string
          description: The user's 4-digit MTN airtime-transfer PIN. Never stored.
          example: '1234'
        reference:
          type: string
          maxLength: 64
          description: Your unique reference. Repeating it never sends twice.
          example: order-2026-0001
    Transfer:
      type: object
      properties:
        success:
          type: boolean
        transfer_id:
          type: string
          example: ACT_5d0c8b1e
        reference:
          type: string
          example: order-2026-0001
        session_id:
          type: string
        amount:
          type: integer
          example: 1000
        status:
          type: string
          enum:
            - success
            - failed
            - pending
            - unknown
        mtn_transaction_id:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
          description: MTN's own reply for this transfer.
        created_at:
          type: string
    Error:
      type: object
      required:
        - message
      properties:
        message:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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