Making Your First Request

Let's walk through making your first API request to purchase airtime.

Complete Example

Here's a complete example of purchasing R10 Vodacom airtime using different programming languages:

Node.js / JavaScript

const axios = require("axios");

const purchaseAirtime = async () => {
  try {
    const response = await axios.post(
      "https://api.pagamio.com/api/v1/purchase",
      {
        productCode: "AIR-VOD-001", // Vodacom R10 Airtime
        amount: 10.0,
        mobileNumber: "+27821234567",
        paymentMethod: "cash",
        channelId: "YOUR_CHANNEL_ID"
      },
      {
        headers: {
          Authorization: "Bearer YOUR_BEARER_TOKEN",
          "Content-Type": "application/json",
        },
      }
    );

    console.log("Success:", response.data);
    return response.data;
  } catch (error) {
    console.error("Error:", error.response.data);
    throw error;
  }
};

// Call the function
purchaseAirtime();

Python

import requests
import time

def purchase_airtime():
    url = 'https://api.pagamio.com/api/v1/purchase'

    headers = {
        'Authorization': 'Bearer YOUR_BEARER_TOKEN',
        'Content-Type': 'application/json'
    }

    payload = {
        'productCode': 'AIR-VOD-001',
        'amount': 10.00,
        'mobileNumber': '+27821234567',
        'paymentMethod': 'cash',
        'channelId': 'YOUR_CHANNEL_ID'
    }

    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()

        print('Success:', response.json())
        return response.json()
    except requests.exceptions.RequestException as error:
        print('Error:', error.response.json())
        raise

# Call the function
purchase_airtime()

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import org.json.JSONObject;

public class PagamioExample {

    public static void purchaseAirtime() throws Exception {
        String url = "https://api.pagamio.com/api/v1/purchase";

        // Create payload
        JSONObject payload = new JSONObject();
        payload.put("productCode", "AIR-VOD-001");
        payload.put("amount", 10.00);
        payload.put("mobileNumber", "+27821234567");
        payload.put("paymentMethod", "cash");
        payload.put("channelId", "YOUR_CHANNEL_ID");

        // Create HTTP client
        HttpClient client = HttpClient.newHttpClient();

        // Build request
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Authorization", "Bearer YOUR_BEARER_TOKEN")
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(payload.toString()))
                .build();

        try {
            // Send request
            HttpResponse<String> response = client.send(request,
                    HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() == 200) {
                System.out.println("Success: " + response.body());
            } else {
                System.err.println("Error: " + response.body());
                throw new Exception("Purchase failed");
            }
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            throw e;
        }
    }

    public static void main(String[] args) {
        try {
            purchaseAirtime();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

cURL

curl -X POST https://api.pagamio.com/api/v1/purchase \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productCode": "AIR-VOD-001",
    "amount": 10.00,
    "mobileNumber": "+27821234567",
    "paymentMethod": "cash",
    "channelId": "YOUR_CHANNEL_ID"
  }'

Understanding the Response

Success Response

{
    "transactionId": "064b0cc0-60c9-4012-94c7-4cc095b6281e",
    "responseCode": "0",
    "responseMessage": "Purchase successful",
    "responseDateTime": "2025-10-21T12:38:51.266157386",
    "successful": true,
    "receipt": {
        "rechargeType": "PINLESS",
        "callCentre": "082111",
        "rechargeVendor": "AirtimeStub",
        "amount": 1000,
        "aggregator": "FLASH"
    }
}

Key Response Fields:

• transactionId - Unique identifier for the transaction
• status - Transaction status (COMPLETED, FAILED, PENDING)
• responseCode - Numeric code (0 = success)
• responseMessage - Human-readable message
• receipt - Transaction receipt details

Error Response

{
    "responseCode": "1103",
    "responseMessage": "Insufficient balance. Available: R0.00"
}

Common First-Time Issues

Issue 1: Invalid Phone Number Format

Error:

{
    "responseCode": "1300",
    "responseMessage": "Invalid phone number format"
}

Solution: Ensure phone numbers are in international format with country code:

• ✅ Correct: +27821234567
• ❌ Wrong: 0821234567, 27821234567

Issue 2: Missing Required Fields

Error:

{
    "responseCode": "1300",
    "responseMessage": "Required fields missing."
}

Solution: Verify all required fields are included:

• productCode
• amount
• mobileNumber
• paymentMethod
• channelId

Issue 3: Invalid Product Code

Error:

{
    "responseCode": "1300",
    "responseMessage": "Vas Product with code AIR-VOD-0018 not found"
}

Solution: Verify the product code exists and is active. Use the Products API to get valid product codes.

Issue 4: Unauthorized

Error:

{
    "responseCode": "1105",
    "responseMessage": "User is not allowed to perform this action"
}

Solution: Check your Bearer token:

• Ensure the Authorization header is correctly formatted
• Verify the Bearer token hasn't been deactivated
• Confirm you're using the correct environment (sandbox vs production)

Next Steps

Now that you've made your first successful request:

1. Explore Other Products

   • Try purchasing data bundles
   • Test electricity tokens
   • Experiment with entertainment vouchers

2. Implement Error Handling

   • Handle network failures gracefully
   • Implement retry logic for transient errors
   • Display user-friendly error messages

3. Add Transaction History

   • Query completed transactions
   • Display receipts to users
   • Implement transaction search

4. Set Up Webhooks

   • Receive real-time transaction updates
   • Automate receipt delivery
   • Monitor transaction status

---

Last updated: October 2025