API Documentation

The Mobile Top-up Platform API allows merchants to integrate airtime purchasing capabilities directly into their applications. Our RESTful API provides endpoints for checking balance, purchasing airtime, and retrieving transaction history.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Base URL: https://api.topupplatform.com/v1

The API uses API keys to authenticate requests. You can view and manage your API keys from the merchant dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, etc.

Authentication to the API is performed via HTTP Bearer Auth. Provide your API key as the bearer token value.

Authorization: Bearer YOUR_API_KEY

Request

GET /balance
Authorization: Bearer YOUR_API_KEY

Response

{
  "success": true,
  "data": {
    "balance": 1250.75,
    "currency": "MMK"
  }
}

Request

POST /airtime
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "phoneNumber": "5551234567",
  "amount": 10.00
}

Response

{
  "success": true,
  "data": {
    "orderId": "ord_123456789",
    "phoneNumber": "5551234567",
    "amount": 10.00,
    "status": "pending",
    "createdAt": "2023-06-15T14:30:45Z"
  }
}

Request

GET /orders/ord_123456789
Authorization: Bearer YOUR_API_KEY

Response

{
  "success": true,
  "data": {
    "orderId": "ord_123456789",
    "phoneNumber": "5551234567",
    "amount": 10.00,
    "status": "completed",
    "operatorResponse": {
      "transactionId": "tx_987654321",
      "message": "Airtime successfully delivered"
    },
    "createdAt": "2023-06-15T14:30:45Z",
    "updatedAt": "2023-06-15T14:30:50Z"
  }
}

Request

GET /transactions?limit=10&page=1
Authorization: Bearer YOUR_API_KEY

Response

{
  "success": true,
  "data": {
    "transactions": [
      {
        "orderId": "ord_123456789",
        "type": "airtime",
        "phoneNumber": "5551234567",
        "amount": 10.00,
        "status": "completed",
        "createdAt": "2023-06-15T14:30:45Z"
      },
      {
        "orderId": "ord_123456788",
        "type": "airtime",
        "phoneNumber": "5557654321",
        "amount": 5.00,
        "status": "completed",
        "createdAt": "2023-06-14T10:15:30Z"
      }
    ],
    "pagination": {
      "total": 42,
      "page": 1,
      "limit": 10,
      "pages": 5
    }
  }
}

The API uses the following error codes: