EasyTopup API

API requests are authenticated using API keys issued from your dashboard. Each request must include your API key in the Authorization header. Keep your API keys secret — do not embed them in client-side code or public repositories.

Keys can be created, rotated, and revoked from the API section of your dashboard. If a key is compromised, revoke it immediately and generate a new one.

Authorization: Bearer YOUR_API_KEY

Retrieve the list of available top-up products, operators, and countries. Products are filtered by country and operator to show only those eligible for a given recipient number.

GET https://easytopup.app/api/products?country=SG&operator=Singtel

Response 200:
{
  "products": [
    {
      "id": "prod_abc123",
      "name": "Singtel $10 Top-up",
      "operator": "Singtel",
      "country": "SG",
      "face_value": 10,
      "currency": "SGD",
      "price": 10.50,
      "processing_time": "instant"
    }
  ]
}

Submit a top-up order by providing the recipient number, country, product ID, and a unique idempotency key. The idempotency key ensures that duplicate submissions (e.g. from a retry) do not create duplicate orders or duplicate recharges.

POST https://easytopup.app/api/orders
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: your-unique-key-123

{
  "recipient_msisdn": "6591234567",
  "country": "SG",
  "product_id": "prod_abc123",
  "payment_method": "wallet"
}

Response 201:
{
  "order_id": "ord_xyz789",
  "status": "processing",
  "payment_status": "paid",
  "fulfilment_status": "queued"
}

Query the status of an order at any time. The response separates payment status from fulfilment status so you can distinguish "paid but not yet delivered" from "fully delivered."

GET https://easytopup.app/api/orders/ord_xyz789

Response 200:
{
  "order_id": "ord_xyz789",
  "payment_status": "paid",
  "fulfilment_status": "delivered",
  "delivered_at": "2026-10-02T03:15:00Z"
}

Fulfilment status values: queued, processing, delivered, failed, unknown (provider timeout — under investigation).

Register a webhook endpoint in your dashboard to receive real-time updates when an order's payment or fulfilment status changes. Webhook payloads are signed — verify the signature using your webhook secret to confirm authenticity before processing.

POST https://your-server.com/webhooks/easytopup
Content-Type: application/json
X-EasyTopup-Signature: t=1696233600,v1=hex_signature...

{
  "event": "order.fulfilment.delivered",
  "order_id": "ord_xyz789",
  "timestamp": "2026-10-02T03:15:00Z",
  "data": { "fulfilment_status": "delivered" }
}

Respond with a 200 status within 10 seconds. We retry failed deliveries with exponential backoff. Duplicate webhook deliveries may occur — handle them idempotently using the order_id and event fields.

API requests are rate-limited per account. Standard limits are 60 requests per minute for read endpoints and 10 requests per minute for order submission. Rate limit headers are included in every response.

Use exponential backoff with jitter for retries. On 429 (rate limited) or 5xx (server error), back off and retry. On 4xx client errors, do not retry without fixing the request. Always use a new idempotency key only for new logical operations — reuse the same key when retrying the same operation.