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

# Purchase airtime

> Purchase airtime via merchant VAS API. Scope: `vas:write`. Requires `Idempotency-Key`.

> [!NOTE]
>
> Pick `network` from **List billers** (`category=airtime`). Requires `Idempotency-Key`.


## OpenAPI

````yaml POST /api/v1/merchant/vas/airtime
openapi: 3.1.0
info:
  title: SendPadi Merchant API
  version: 1.0.0
  description: >-
    Merchant REST API. Authenticate with HMAC headers (`X-Api-Key`,
    `X-Timestamp`, `X-Signature`). Generate playground headers with [Sign
    requests (playground)](/guides/sign-requests).
servers:
  - url: https://api.sendpadi.com
    description: Production (test + live keys)
security: []
paths:
  /api/v1/merchant/vas/airtime:
    post:
      tags:
        - vas
      summary: Purchase airtime
      description: >-
        Purchase airtime via merchant VAS API. **Scope:** `vas:write`. Requires
        `Idempotency-Key` on this write.
      operationId: api-reference_vas_airtime
      parameters:
        - name: X-Timestamp
          in: header
          required: true
          description: Unix time in seconds
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          description: HMAC-SHA256 signature
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: true
          description: UUID. Required on money-moving writes.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phoneNumber:
                  type: string
                network:
                  type: string
                  enum:
                    - MTN
                    - AIRTEL
                    - GLO
                    - NINE_MOBILE
                  description: Mobile network from List billers (`category=airtime`)
                amount:
                  type: integer
              required:
                - phoneNumber
                - network
                - amount
            example:
              phoneNumber: 080*******8
              network: MTN
              amount: 50
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              example:
                success: true
                data:
                  transactionId: vas_airtime_001
                  reference: AIRTIME-************-****
                  status: completed
                  message: Transaction submitted
                  details:
                    reference: AIRTIME-************-****
                    transactionId: vas_airtime_001
                    status: completed
                    userMessage: Transaction submitted
                    retryAfterSeconds: 3
              examples:
                success:
                  summary: Success
                  value:
                    success: true
                    data:
                      transactionId: vas_airtime_001
                      reference: AIRTIME-************-****
                      status: completed
                      message: Transaction submitted
                      details:
                        reference: AIRTIME-************-****
                        transactionId: vas_airtime_001
                        status: completed
                        userMessage: Transaction submitted
                        retryAfterSeconds: 3
        '400':
          description: Amount exceeds maximum
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              examples:
                amount_exceeds_maximum:
                  summary: Amount exceeds maximum
                  value:
                    success: false
                    data:
                      transactionId: null
                      reference: null
                      status: FAILED
                      message: >-
                        We couldn't process your request: Maximum airtime
                        purchase amount is 10000 NGN. Please check your details
                        and try again.
                    error: VALIDATION_ERROR
              example:
                success: false
                data:
                  transactionId: null
                  reference: null
                  status: FAILED
                  message: >-
                    We couldn't process your request: Maximum airtime purchase
                    amount is 10000 NGN. Please check your details and try
                    again.
                error: VALIDATION_ERROR
        '401':
          description: Invalid HMAC signature
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              examples:
                invalid_hmac_signature:
                  summary: Invalid HMAC signature
                  value:
                    success: false
                    message: Invalid request signature
                    error: true
                    errorCode: MERCHANT_AUTH_SIGNATURE_INVALID
              example:
                success: false
                message: Invalid request signature
                error: true
                errorCode: MERCHANT_AUTH_SIGNATURE_INVALID
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key id (sp_test_… / sp_live_…)

````

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