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

# Receive airtime callback

> Webhook your application must implement. Beem POSTs the final transfer status to your configured callback URL. Replace the server URL with your own HTTPS endpoint.



## OpenAPI

````yaml /openapi/airtime.json post /airtime/callback
openapi: 3.0.3
info:
  title: Beem Airtime API
  version: 1.0.0
  description: >-
    Airtime top-up, transaction status, credit balance, and customer callbacks.
    Transfer and status endpoints are served by the Airtime API; credit balance
    is served by the shared Topup service (use app_name=AIRTIME or USSD).
  contact:
    name: Beem
    url: https://beem.africa
    email: support@beem.africa
servers:
  - url: https://apiairtime.beem.africa
    description: Airtime API — transfer & transaction status
  - url: https://apitopup.beem.africa/v1
    description: Topup API — credit balance (shared across products)
security: []
tags: []
paths:
  /airtime/callback:
    post:
      summary: Receive airtime callback
      description: >-
        Webhook your application must implement. Beem POSTs the final transfer
        status to your configured callback URL. Replace the server URL with your
        own HTTPS endpoint.
      operationId: receiveAirtimeCallback
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  description: Status code (100 = success)
                  type: integer
                message:
                  description: Human-readable status message
                  type: string
                args:
                  type: object
                  properties:
                    timestamp:
                      description: Transaction timestamp (ISO 8601)
                      type: string
                    transaction_id:
                      description: Beem transaction ID
                      anyOf:
                        - type: string
                        - type: number
                          format: float
                    amount:
                      description: Airtime amount transferred
                      anyOf:
                        - type: string
                        - type: number
                          format: float
                    dest_addr:
                      description: Recipient mobile number
                      type: string
                    reference_id:
                      description: Client reference ID from the original transfer request
                      anyOf:
                        - type: string
                        - type: number
                          format: float
                  additionalProperties: false
                  required:
                    - timestamp
                    - transaction_id
                    - amount
                    - dest_addr
              additionalProperties: false
              required:
                - code
                - message
                - args
      responses:
        default:
          description: Successful response
      servers:
        - url: https://example.com
          description: Your callback server — replace with your URL

````