Merchant API Documentation

Powerful, RESTful endpoints for integrating mobile recharge and utility payments into your platform. Production-ready in under a day.

API v1.2 • Online
Base URL: api.nepalitop.com
Get API Key

Everything You Need to Integrate

API Keys + OAuth 2.0

Two-tier auth: API keys for server-to-server, OAuth tokens for partner apps.

Webhook Callbacks

Real-time status updates for transactions. Retry logic built-in for failed deliveries.

Sandbox Environment

Full sandbox at sandbox.nepalitop.com — test all endpoints without real transactions.

Enterprise Security

AES-256, TLS 1.3, HMAC signature verification on all webhook payloads.

SDKs Available

Official SDKs for Node.js, Python, PHP, and Java. Community packages for others.

Comprehensive Docs

Every endpoint documented with request/response examples and error codes.

Authentication

All API requests must be authenticated using your API key in the Authorization header. Keys are generated from your partner dashboard.

API keys are merchant-specific and environment-scoped (live vs sandbox)
Never expose keys in client-side code or public repositories
Keys can be rotated anytime from your dashboard
IP whitelisting available for additional security
# HTTP Authorization Header
Authorization: Bearer nt_live_abc123xyz...
# Example cURL request
curl -X POST \
https://api.nepalitop.com/v1/recharge \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"operator":"ncell","mobile":"9841XXXXXX","amount":500}'
POST/v1/recharge

Mobile Recharge

Live

Request Body

{
  "operator": "ncell",        // ncell | ntc | smartcell
  "mobile": "9841XXXXXX",    // 10-digit Nepal mobile
  "amount": 500,             // NPR amount (50–10000)
  "currency": "NPR",         // NPR | QAR | AED | SAR
  "reference": "TXN_001",    // Your unique reference
  "notify_mobile": true      // Send SMS to recipient
}

Response 200 OK

{
  "status": "SUCCESS",
  "txn_id": "NT-84729542",
  "operator_ref": "NCL-XYZ-001",
  "operator": "ncell",
  "mobile": "9841XXXXXX",
  "amount_recharged": 500,
  "currency": "NPR",
  "processing_time_ms": 2142,
  "timestamp": "2026-03-04T08:00:00Z"
}
POST/v1/bill/pay

Bill Payment

Request Body

{
  "service": "nea",          // nea | khanepani | internet
  "customer_id": "012345",   // Service customer ID
  "amount": 4850,            // Amount due (or partial)
  "currency": "NPR",
  "reference": "BILL_001"
}

Response 200 OK

{
  "status": "SUCCESS",
  "txn_id": "NT-84729543",
  "service": "nea",
  "customer_id": "012345",
  "customer_name": "R. Adhikari",
  "amount_paid": 4850,
  "bill_period": "Kartik 2081",
  "timestamp": "2026-03-04T08:05:00Z"
}

All Endpoints

MethodEndpoint
GET/v1/status
POST/v1/recharge
POST/v1/bill/fetch
POST/v1/bill/pay
GET/v1/transactions
GET/v1/transactions/:id
GET/v1/balance
POST/v1/webhooks

Ready to integrate?

Get your API key in minutes. Use our sandbox to test, then go live with one config change. Production onboarding takes less than 24 hours.

Get API Key Talk to our Engineers