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

# Sending airtime

> Send an airtime top-up request to a mobile number.

Use `POST /v1/transfer` to send airtime credit to a mobile number on a supported network.

**Endpoint:** `https://apiairtime.beem.africa/v1/transfer`

***

## Request parameters

### Headers

| Header          | Required | Description                                                                                                            |
| --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `Authorization` | Yes      | Basic Auth (`Basic base64(api_key:secret_key)`) or access token — see [Authentication](/guides/airtime/authentication) |
| `Content-Type`  | Yes      | `application/json`                                                                                                     |

### Body

| Parameter      | Type   | Required | Description                                                                          |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| `dest_addr`    | String | Yes      | Mobile number in international format without a leading `+`. Example: `255784825785` |
| `amount`       | Number | Yes      | Airtime amount. Supports up to 2 decimal places                                      |
| `reference_id` | String | Yes      | Unique reference ID generated by your application. Example: `ref_id_215372`          |

***

## Sample request body

```json theme={null}
{
  "dest_addr": "255784825785",
  "amount": 500,
  "reference_id": "ref_id_215372"
}
```

***

## Sample implementations

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const axios = require("axios");
    const https = require("https");
    const btoa = require("btoa");

    const api_key = "<api_key>";
    const secret_key = "<secret_key>";
    const url = "https://apiairtime.beem.africa/v1/transfer";

    const payload = {
      dest_addr: "<dest_addr>",
      amount: "<amount>",
      reference_id: "<reference_id>",
    };

    axios
      .post(url, payload, {
        headers: {
          "content-type": "application/json",
          Authorization: "Basic " + btoa(api_key + ":" + secret_key),
        },
        httpsAgent: new https.Agent({ rejectUnauthorized: false }),
      })
      .then((resp) => console.log(resp.data))
      .catch((err) => console.log(err.message));
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    <?php
    $url = "https://apiairtime.beem.africa/v1/transfer";
    $api_key = '<api_key>';
    $secret_key = '<secret_key>';

    $body = [
      'dest_addr' => '<dest_addr>',
      'amount' => '<amount>',
      'reference_id' => '<reference_id>',
    ];

    $ch = curl_init($url);
    curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
        'Authorization: Basic ' . base64_encode("$api_key:$secret_key"),
        'Content-Type: application/json',
      ],
      CURLOPT_POSTFIELDS => json_encode($body),
      CURLOPT_SSL_VERIFYHOST => 0,
      CURLOPT_SSL_VERIFYPEER => 0,
    ]);

    $response = curl_exec($ch);
    if ($response === false) {
      die(curl_error($ch));
    }
    var_dump($response);
    ?>
    ```
  </Tab>

  <Tab title="GitHub">
    Full sample implementations:

    [beem-airtime-api-sample — send](https://github.com/beemafrica/beem-airtime-api-sample/tree/master/send)
  </Tab>
</Tabs>

***

## Success response

On a valid request, the platform returns **HTTP 200** or **HTTP 201** with:

```json theme={null}
{
  "code": 200,
  "transaction_id": "1571324535091",
  "message": "Disbursement is in progress"
}
```

| Field            | Description                                                  |
| ---------------- | ------------------------------------------------------------ |
| `code`           | Response code (e.g. `200`)                                   |
| `transaction_id` | Unique transaction ID generated by Beem                      |
| `message`        | Transaction description (e.g. `Disbursement is in progress`) |

Store the `transaction_id` — use it to check status via [Transaction status](/guides/airtime/transaction-status) or match against [Callbacks](/guides/airtime/callbacks).

***

## Failure response

On an invalid request, the platform returns **HTTP 400 Bad Request**:

```json theme={null}
{
  "errors": [
    {
      "code": 102,
      "message": "Invalid phone number",
      "args": {
        "msisdn": "2556536795531"
      }
    }
  ]
}
```

See [Response codes](/guides/airtime/response-codes) for all error codes.