API Access & Keys
Generate an API key to integrate EasyTopup's top-up, eSIM, voucher, and bill payment services directly into your own platform. API access is available to approved dealer and reseller accounts.
API Base URL
All API requests should be sent to this base URL. Append the endpoint path for each operation.
https://easytopup.app
Generate Your API Key
Verify your account
Ensure your account has completed KYC verification and has an active dealer or reseller role. If you haven't applied yet, apply for API access.
Create a personal access token
Go to your workspace Settings → Secrets → Personal access tokens → Create access token. Choose One app or Superagent and select the EasyTopup app, then choose Full access or Read-only depending on your integration needs.
Copy and store your token securely
Copy the token when it is shown — it won't be displayed again. Store it in a secure secrets manager (never in client-side code or public repositories). This token is your API key for all EasyTopup API requests.
Start making API calls
Include your token in the Authorization header of every request. See the quick-start examples below.
Quick Start
Authentication
Every request must include your API key as a Bearer token:
curl -X GET https://easytopup.app/api/products \ -H "Authorization: Bearer YOUR_API_KEY"
List Products
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
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"
}Check Order Status
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"
}Rate Limits
- • 60 requests/min for read endpoints
- • 10 requests/min for order submission
- • Rate limit headers included in every response
- • Use exponential backoff with jitter for retries
Security
- • Never embed API keys in client-side code
- • Rotate keys regularly from your dashboard
- • Revoke compromised keys immediately
- • Use idempotency keys for all order submissions
Webhooks
Register a webhook endpoint 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 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" }
}