Airtime Top-Up API Endpoint 2026 | Pairgate Developer Docs

Endpoint

Send a POST request with the purchase details in the request body.

Production URL

https://pairgate.com/api/v1/airtime/purchase

Method POST

Test Endpoint

https://pairgate.com/api/v1/test/airtime/purchase

Authentication

This request requires a valid Bearer token.

Header	Value	Description
`Authorization`	`Bearer {token}`	Your unique API authorization token
`Content-Type`	`application/json`	Required for POST requests

Body Parameters

All parameters are required. Send them as JSON in the request body.

Parameter	Type	Required	Description
`provider_id`	string	Yes	Provider slug (e.g. `mtn`, `airtel`, `glo`, `9mobile`)
`amount`	float	Yes	Amount to send in Naira (minimum ₦50)
`recipient`	string	Yes	Mobile number (11 digits starting with 0, or 13 digits starting with 234)
`reference`	string	Yes	Your unique reference for this transaction (8–100 characters)

Code Examples

Choose your preferred language below. Replace the parameters and YOUR_API_KEY with your actual values.

PHP (Laravel)

// Purchase Airtime
$response = Http::withHeaders([
    'Authorization' => 'Bearer YOUR_API_KEY',
    'Content-Type' => 'application/json',
])->post('https://pairgate.com/api/v1/airtime/purchase', [
    'provider_id' => 'mtn',
    'amount' => 500,
    'recipient' => '08031234567',
    'reference' => 'my-airtime-order-001',
]);

$result = $response->json();

dd($result);

cURL

curl -X POST "https://pairgate.com/api/v1/airtime/purchase" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "mtn",
    "amount": 500,
    "recipient": "08031234567",
    "reference": "my-airtime-order-001"
  }'

Node.js

const axios = require('axios');

const purchaseAirtime = async () => {
    try {
        const response = await axios.post(
            'https://pairgate.com/api/v1/airtime/purchase',
            {
                provider_id: 'mtn',
                amount: 500,
                recipient: '08031234567',
                reference: 'my-airtime-order-001'
            },
            {
                headers: {
                    'Authorization': 'Bearer YOUR_API_KEY',
                    'Content-Type': 'application/json'
                }
            }
        );
        
        console.log(response.data);
    } catch (error) {
        console.error(error.response?.data || error.message);
    }
};

purchaseAirtime();

Python

import requests
import json

url = "https://pairgate.com/api/v1/airtime/purchase"

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "provider_id": "mtn",
    "amount": 500,
    "recipient": "08031234567",
    "reference": "my-airtime-order-001"
}

try:
    response = requests.post(url, headers=headers, json=payload)
    response.raise_for_status()
    data = response.json()
    print(json.dumps(data, indent=2))
except requests.exceptions.RequestException as e:
    print(f"Error: {e}")

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

String jsonBody = "{"
    + "\"provider_id\": \"mtn\","
    + "\"amount\": 500,"
    + "\"recipient\": \"08031234567\","
    + "\"reference\": \"my-airtime-order-001\""
    + "}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://pairgate.com/api/v1/airtime/purchase"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
    .build();

try {
    HttpResponse response = client.send(request, 
        HttpResponse.BodyHandlers.ofString());
    
    System.out.println(response.body());
} catch (Exception e) {
    System.err.println("Error: " + e.getMessage());
}

Example Request Body

{
  "provider_id": "mtn",
  "amount": 500,
  "recipient": "08031234567",
  "reference": "my-airtime-order-001"
}

Response Format

Success Response (200)

{
  "code": 200,
  "status": "success",
  "data": {
    "status": true,
    "message": "Airtime purchase successful & processing.",
    "reference_code": "TRXVTU20260615104818CQ3",
    "balance_before": 2000.00,
    "balance_after": 1500.00,
    "amount": 500.00,
    "plan": "Airtime",
    "recipient": "08031234567"
  }
}

Test Response (200)

{
  "code": 200,
  "status": "success",
  "data": {
    "test_mode": true,
    "message": "This is a test — no balance deducted.",
    "request": {
      "provider_id": "mtn",
      "amount": 500,
      "recipient": "08031234567",
      "reference": "my-airtime-order-001"
    },
    "would_deduct": 500.00,
    "balance": 2000.00
  }
}

Response Fields

Field	Type	Description
`status`	boolean	`true` if successful
`message`	string	Status description
`reference_code`	string	Your transaction reference for status checks
`balance_before`	float	Wallet balance before debit
`balance_after`	float	Wallet balance after debit
`amount`	float	Amount charged
`plan`	string	Always `Airtime`
`recipient`	string	Mobile number receiving the airtime

Error Responses

The following errors may occur when calling this endpoint.

Status	Code	Description
422	`Invalid provider`	Provider not found or inactive
422	`Minimum amount`	Amount is below ₦50
422	`Insufficient balance`	Wallet balance is too low
422	`Duplicate reference`	This reference has already been used
401	`Missing API key`	No Bearer token provided
401	`Invalid API key`	Token does not match any active key
403	`Suspended`	API key or account has been suspended
429	`Rate limited`	Too many requests

Airtime Purchase

Quick Summary