API Documentation for Buying Airtime

This endpoint allows fintech developers to purchase airtime for Nigerian networks securely via MyBundlePay’s API.

Important: You must first fetch the list of airtime billers using the /api/airtime-billers/NG endpoint to get valid biller identifiers.


POST https://mybundlepay.com/ng/api/buy-airtime

HEADERS

Authorization* string

Pass your {secret_key} as a Bearer token in the request header to authorize this call.

REQUEST BODY

application/json format

  • amount * - Numeric, amount in Naira to recharge (minimum 1)
  • biller * - String, valid biller identifier obtained from the billers endpoint
  • mobile * - String, mobile phone number to recharge (e.g., 081xxxxxxxx)

EXAMPLE REQUEST (PHP cURL)


<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://mybundlepay.com/ng/api/buy-airtime',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode([
      "amount" => 100,
      "biller" => "mtn-ng",
      "mobile" => "081xxxxxxxx"
  ]),
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer {secret_key}'
  ),
));

$response = curl_exec($curl);
curl_close($curl);
echo $response;

SUCCESS RESPONSE


{
    "status": "success",
    "message": "Airtime purchase successful",
    "transaction_ref": "BP-ABC123",
    "amount": 100,
    "charge": 5.50
}

ERROR RESPONSES


{
    "status": "failed",
    "message": "Account balance is insufficient"
}
{
    "status": "failed",
    "message": "Authentication error. Please login again."
}
{
    "status": "failed",
    "message": "Invalid token"
}
{
    "status": "failed",
    "message": "Unsupported bill type"
}

                        

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://mybundlepay.com/ng/api/buy-airtime",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => json_encode([
        "amount" => 100,
        "biller" => "mtn-ng",
        "mobile" => "081xxxxxxxx"
    ]),
    CURLOPT_HTTPHEADER => array(
        "Authorization: Bearer {secret_key}",
        "Content-Type: application/json"
    ),
));

$response = curl_exec($curl);
curl_close($curl);
echo $response;

                                

const axios = require('axios');

axios.post('https://mybundlepay.com/ng/api/buy-airtime', {
    amount: 100,
    biller: 'mtn-ng',
    mobile: '081xxxxxxxx'
}, {
    headers: {
        Authorization: 'Bearer {secret_key}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error.response ? error.response.data : error.message);
});