Retailer API integration guide
Connect your own website, mobile app, POS or business system to your NowPay retailer wallet.
1. Before you start
You need an approved retailer account, Reseller API enabled by the administrator, and enough available wallet balance. Customer and admin accounts cannot use retailer API keys.
On the website, open Reseller API, give the key a label and confirm your six-digit payment PIN. Copy the full key immediately: it is shown once and stored only as a hash. Up to five active keys are allowed. Your mobile login token is not a reseller API key.
Start with the read-only balance, operator and package requests. A live POST /reloads spends real wallet funds and sends a real reload. Replace every placeholder and confirm the actual recipient before submitting. There is no public sandbox endpoint in this API.
2. Connect your own application
- Your customer app → your authenticated backend → NowPay HTTPS API. Return only the order result to your app.
- Store NOWPAY_API_KEY in a server environment variable or secret manager. Never put it in browser JavaScript, a distributed Android/iOS app, Git, screenshots or URLs.
- Authenticate and authorize users on your own backend, validate the service, recipient and amount, and require their payment approval. Do not expose an anonymous proxy that lets anyone spend your retailer wallet.
- Create a local order first and persist its unique reference and exact request. Record the NowPay reference, final status and actual debit for reconciliation.
- The API key authorizes wallet spending; API reloads do not ask for a payment PIN on each call. Confirming your PIN is required when creating the key on the website.
3. Authentication and your first request
Use HTTPS and send Authorization: Bearer <your key> on every request. X-API-Key: <your key> is also supported. Keys in URL parameters or JSON bodies do not authenticate a request. Send Content-Type: application/json for POST requests.
The examples read NOWPAY_API_KEY from your server environment. Do not paste an actual key into the documentation or share it with support.
cURL commands use Bash/POSIX shell syntax. On Windows, run them in Git Bash/WSL or use the Node.js/Python examples.
Wallet balance API
GET /api/v1/balance returns the current wallet balance belonging to the approved retailer whose API key you send. No request body or account ID is needed. Other accounts and internal TM Hub/SMSlenz balances are not included.
This read-only request does not debit your wallet, send a reload or send an SMS. HTTP 200 returns success:true with data.balance as a two-decimal string and data.currency as LKR. A genuine empty wallet returns "0.00"; errors must be shown as unavailable, never replaced with zero.
Display the balance to authorized staff through your own authenticated backend. Keep the API key on your server. Refresh on demand or about once per minute while the screen is open; balance requests share the 60 requests/minute per-key limit with all other API calls.
The balance is a snapshot, not a reserved amount or a guarantee that the next payment will succeed. Use decimal arithmetic; the server checks funds when placing each order. After a reload, POST /reloads includes the remaining data.balance; GET /reloads/{reference} does not.
Authentication and feature gates are unchanged: 401 for missing, invalid or revoked keys; 403 for inactive accounts or IP/HTTPS restrictions; 404 when the API feature is disabled; 429 when rate limited. Show the last successful reading as stale after a failed refresh, or show unavailable if there is none.
Read wallet balance with cURL
curl --request GET "https://nowpay.lk/api/v1/balance" \
--header "Authorization: Bearer $NOWPAY_API_KEY"
Illustrative HTTP 200 balance response
{
"success": true,
"data": {
"balance": "12500.50",
"currency": "LKR"
}
}
Read balance on your Node.js server
// Server-side Node.js 22+. Set NOWPAY_API_KEY in your environment.
const key = process.env.NOWPAY_API_KEY;
if (!key) throw new Error("Set NOWPAY_API_KEY on the server");
const response = await fetch("https://nowpay.lk/api/v1/balance", {
headers: { Authorization: "Bearer " + key },
redirect: "error", signal: AbortSignal.timeout(15000), cache: "no-store"
});
const body = await response.json();
if (!response.ok || body.success !== true) {
throw new Error(body.error?.code || "BALANCE_UNAVAILABLE");
}
// Keep balance as a decimal string; use a decimal library for money calculations.
console.log(body.data.balance, body.data.currency);
4. Endpoints
Paths above are relative to the base URL. There are no bulk-reload, electricity/water payment, wallet-credit, API-key creation or webhook-registration endpoints in this reseller API. Keys are managed on the website.
| Method and path | What it does |
|---|---|
| GET /balance | Available retailer wallet balance in LKR; read-only. |
| GET /operators | Current operator codes, names, enabled flags, pricing modes and retailer rates. |
| GET /packs?operator=DIALOG | Active data packages; the optional operator filter is case-insensitive. Store and submit the returned package id. |
| POST /reloads | Create a prepaid, postpaid, data-pack, broadband or DTH payment. |
| GET /reloads/{reference} | Look up your own order by its NowPay reference or your client reference. URL-encode the reference. |
5. Create a reload
POST a JSON object. Field names and enum values stay in English in all language versions. Keep phone and account numbers as strings so leading zeroes are preserved.
| Field | Requirement and meaning |
|---|---|
| service | Optional; defaults to prepaid. Use prepaid, postpaid, data-pack, broadband or dth. |
| operator | Required. Use a NowPay code from GET /operators, such as DIALOG or DISHTV; do not send TM provider numbers such as 101 or 302. |
| number | Required string. Recipient mobile, router or TV/card account number matching the selected service/operator. |
| amount | Required except data-pack. Positive amount with up to two decimal places; send a decimal string. The currency is face_currency from the operator. |
| pack_id | Required only for data-pack. Use an active id from GET /packs for the same operator; the server uses its current price, not a client-supplied amount. |
| reference | Required string: 1–64 ASCII letters, digits, dots, underscores or hyphens. Unique per new payment for your retailer account; reuse it only for an identical retry. |
Prepaid request with cURL
curl --request POST "https://nowpay.lk/api/v1/reloads" \
--header "Authorization: Bearer $NOWPAY_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"service": "prepaid",
"operator": "DIALOG",
"number": "<CUSTOMER_MOBILE>",
"amount": "100.00",
"reference": "YOUR_SAVED_ORDER_ID"
}'
Data-package JSON body
{
"service": "data-pack",
"operator": "DIALOG",
"number": "<CUSTOMER_MOBILE>",
"pack_id": "<ID_FROM_GET_PACKS>",
"reference": "YOUR_SAVED_PACK_ORDER_ID"
}
Indian DTH JSON body
{
"service": "dth",
"operator": "DISHTV",
"number": "<11_DIGIT_CARD_NUMBER>",
"amount": "100.00",
"reference": "YOUR_SAVED_DTH_ORDER_ID"
}
6. Services, operators and recipient formats
An all-zero TV account is invalid. Always fetch the current catalog and use only enabled operators and active packs. A recipient does not need a NowPay account.
| Service / operators | Recipient |
|---|---|
| prepaid / postpaid: DIALOG, MOBITEL, HUTCH, AIRTEL | Sri Lankan mobile string matching the operator. 07XXXXXXXX and equivalent +94/94 formats are normalized. |
| data-pack: mobile operators above, DHBB | Matching mobile or home-broadband number; select a package for that same operator. |
| broadband: DHBB | Dialog home-broadband/router number, ten digits starting with 0; accepted country-code formats are normalized. |
| dth: DTV | Dialog TV account: exactly eight digits. |
| dth: DISHTV, SUNDIRECT | Dish TV / Sun Direct card: exactly eleven digits, including any leading zeroes. |
| dth: D2H | Videocon D2h account: six to twelve digits. |
7. Amounts, commission and wallet debit
Balances, face_amount, debit_amount and rates are decimal strings. Use decimal arithmetic in your own system and retain two-decimal monetary values; do not rely on binary floating-point rounding.
DISCOUNT: wallet debit = face amount × (100 − commission_rate) ÷ 100, rounded half up to two decimals. Illustration only: LKR 100 at 1% costs LKR 99.
MULTIPLIER: wallet debit in LKR = face amount in INR × commission_rate, rounded half up to two decimals. Here commission_rate is LKR per INR, not a percentage. Illustration only: INR 100 at 4.30 costs LKR 430.
Fetch pricing_mode, face_currency and commission_rate from GET /operators instead of hard-coding tariffs. Actual prices and transaction limits may change. There is no reseller quote endpoint: the server applies current pricing at submission. Use the returned debit_amount and balance as the actual charge and remaining wallet balance.
8. Read the response correctly
A new order normally returns HTTP 201; an identical reference replay returns HTTP 200 with duplicate:true and the existing order. A GET lookup returns success:true when the order exists even if its payment status is FAILED.
For POST, success is false for FAILED or REJECTED orders, but the response still has data and can be HTTP 201. HTTP 200/201 and success:true are not by themselves proof of delivery: always inspect data.status.
The JSON below is illustrative. Balances, rates, references and timestamps in your real response differ. created_at/completed_at are ISO timestamps; completed_at, operator_reference and message may be null. balance and duplicate belong to the POST response, not the GET order lookup.
| Response field | Meaning |
|---|---|
| reference / client_reference | NowPay-generated order reference / the reference you saved and sent. |
| service / operator / package / target | Stored service enum (uppercase), operator code, optional package name and normalized recipient. |
| pricing_mode / face_currency | DISCOUNT or MULTIPLIER; face-value currency LKR or INR. |
| face_amount / commission_rate / debit_amount | Service face value, applied retailer rate and actual LKR wallet deduction. |
| status / message / operator_reference | Saved payment state, readable explanation and optional provider reference. |
| created_at / completed_at | Creation time and optional completion time. |
| balance / duplicate | POST-only current LKR balance / whether this was an idempotent replay. |
| error.code / error.message | Machine code and readable explanation on API request errors; inspect data when an order exists. |
Illustrative new-order response
{
"success": true,
"duplicate": false,
"data": {
"reference": "NP_EXAMPLE",
"client_reference": "YOUR_SAVED_ORDER_ID",
"service": "PREPAID",
"operator": "DIALOG",
"package": null,
"target": "0771234567",
"pricing_mode": "DISCOUNT",
"face_currency": "LKR",
"face_amount": "100.00",
"commission_rate": "1.00",
"debit_amount": "99.00",
"status": "SUCCESS",
"operator_reference": "PROVIDER_EXAMPLE",
"message": "Reload delivered",
"created_at": "2026-11-11T06:00:00.000Z",
"completed_at": "2026-11-11T06:00:01.000Z",
"balance": "901.00"
}
}
Illustrative request error
{
"success": false,
"error": {
"code": "INSUFFICIENT_FUNDS",
"message": "Insufficient balance. Required: LKR 99.00."
}
}
9. Retries without duplicate charges
- Save one unique reference and exact payload before the first POST. Use a different reference only for a genuinely new payment.
- After a timeout, connection error or uncertain 5xx response, GET the saved reference. If you retry POST, reuse exactly the same reference, service, operator, recipient, amount and pack.
- If lookup is temporarily 404, the original request may still be in flight. Wait and retry lookup or the identical POST with the same reference; never generate a new payment reference to work around uncertainty.
- Changing details under an existing reference returns 409 REFERENCE_CONFLICT. Retrying the same payment never creates another debit, including concurrent retries.
- For PROCESSING/PENDING, use bounded polling with backoff (for example 5, 10, 20, then 60 seconds) and stop at a final status. All polling counts toward rate limits. Do not automatically refund your customer or claim failure because a response is slow.
Look up the saved reference
curl --request GET "https://nowpay.lk/api/v1/reloads/YOUR_SAVED_ORDER_ID" \
--header "Authorization: Bearer $NOWPAY_API_KEY"
10. Order statuses
GET status reads the saved NowPay order; it is not a direct TM status query. This API has no public callback/webhook contract. Unconfirmed deliveries may require staff/provider review. Never infer delivery just from elapsed time.
| Status | Meaning and action |
|---|---|
| PROCESSING | The wallet debit is recorded and the provider call is in progress. Keep the same reference and wait. |
| SUCCESS | Completed in NowPay. Under the current TM acceptance policy, recognized successful/accepted TM responses finish immediately. |
| PENDING | The outcome is unconfirmed, for example after a timeout or unexpected provider response. Keep the debit; contact support if it persists. |
| FAILED | Provider explicitly rejected the reload; the stored wallet debit is refunded once. |
| REFUNDED | A separately verified cancellation/refund returned the stored debit. |
| REJECTED | Rejected for review. Rejection alone does not refund the wallet. |
11. Errors and rate limits
| HTTP / code | What to do |
|---|---|
| 400 INVALID_REFERENCE / INVALID_OPERATOR / INVALID_PACK / INVALID_TARGET / UNKNOWN_SERVICE / BAD_REQUEST | Fix the invalid field, number format or amount before sending a new intended payment. Do not alter an already accepted payment under the same reference. |
| 401 UNAUTHORIZED | Check the header and full key. A revoked key or account security revocation needs a replacement key. |
| 402 INSUFFICIENT_FUNDS | Fund your retailer wallet through the usual approved funding workflow, then check the saved reference before retrying. |
| 403 ACCOUNT_INACTIVE / IP_NOT_ALLOWED / HTTPS_REQUIRED | Use an approved retailer, the permitted server IP if configured, and HTTPS. Ask support to resolve account restrictions. |
| 404 NOT_FOUND | Check the path and reference. The order may not exist, may belong to another retailer, or the Reseller API feature may be disabled. |
| 405 METHOD_NOT_ALLOWED | Use POST, not GET, to create /reloads. |
| 409 REFERENCE_CONFLICT | Your reference already identifies another payload. Reconcile the original order; do not change its details. |
| 413 | Keep JSON requests below the 20 KB body limit; do not upload files to reseller endpoints. |
| 429 RATE_LIMITED | Limit is 60 requests per minute per key; additional global throttles also apply. Respect Retry-After when present and back off. |
| 503 MAINTENANCE / MAINTENANCE_PREVIEW / SERVICE_DISABLED / OPERATOR_DISABLED / OPERATOR_NOT_CONFIGURED | Pause new submissions. Check service availability and the saved order before any retry. |
| 500 or unreadable/network response | Treat the outcome as uncertain; look up your existing reference before retrying. |
12. Server-side integration examples
These examples belong on your own authenticated backend, not inside your customer app. Replace placeholders, set NOWPAY_API_KEY securely, and persist the order before executing POST. They do not implement your customer authentication, database or authorization.
Keep the exact saved order on any retry. Log only the references and status you need; redact credentials and avoid logging customers’ full payment details. Never disable TLS certificate checks.
Node.js 22+ · fetch
// Node.js 22+; run only on your server.
const API_BASE = "https://nowpay.lk/api/v1";
const key = process.env.NOWPAY_API_KEY;
if (!key) throw new Error("Set NOWPAY_API_KEY on the server");
async function nowpay(method, path, payload) {
const response = await fetch(API_BASE + path, {
method, redirect: "error", signal: AbortSignal.timeout(15000),
headers: { Authorization: "Bearer " + key, "Content-Type": "application/json" },
body: payload === undefined ? undefined : JSON.stringify(payload)
});
const body = await response.json();
if (!response.ok) {
throw Object.assign(new Error(body.error?.message || "API request failed"),
{ httpStatus: response.status, code: body.error?.code });
}
return body;
}
// Replace placeholders and save this exact order in your database BEFORE sending.
const savedOrder = {
"service": "prepaid",
"operator": "DIALOG",
"number": "<CUSTOMER_MOBILE>",
"amount": "100.00",
"reference": "YOUR_SAVED_ORDER_ID"
};
const result = await nowpay("POST", "/reloads", savedOrder);
// HTTP 201 or success:true alone does not prove delivery. Read data.status.
console.log(result.data.reference, result.data.status);
// After a timeout: check this order; never generate a replacement reference.
// const status = await nowpay("GET", "/reloads/" + encodeURIComponent(savedOrder.reference));
Python 3 · standard library
# Python 3; server-side, standard library only.
import json, os, urllib.request, urllib.error
API_BASE = "https://nowpay.lk/api/v1"
key = os.environ["NOWPAY_API_KEY"]
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
opener = urllib.request.build_opener(NoRedirect())
def nowpay(method, path, payload=None):
data = None if payload is None else json.dumps(payload).encode("utf-8")
request = urllib.request.Request(API_BASE + path, data=data, method=method,
headers={"Authorization": "Bearer " + key, "Content-Type": "application/json"})
try:
with opener.open(request, timeout=15) as response:
return response.status, json.load(response)
except urllib.error.HTTPError as error:
return error.code, json.load(error)
# Use your persisted order ID again on every retry of the SAME payment.
saved_order = {"service":"prepaid","operator":"DIALOG","number":"<CUSTOMER_MOBILE>","amount":"100.00","reference":"YOUR_SAVED_ORDER_ID"}
http_status, body = nowpay("POST", "/reloads", saved_order)
if "data" in body:
print(body["data"]["reference"], body["data"]["status"])
else:
print(http_status, body.get("error", {}).get("code"))
PHP 8+ · cURL
<?php // PHP 8+ with the cURL extension; server-side only.
$key = getenv("NOWPAY_API_KEY");
if (!$key) { throw new RuntimeException("Set NOWPAY_API_KEY on the server"); }
// Replace placeholders; persist this exact order before submitting.
$order = ["service" => "prepaid", "operator" => "DIALOG",
"number" => "<CUSTOMER_MOBILE>", "amount" => "100.00",
"reference" => "YOUR_SAVED_ORDER_ID"];
$curl = curl_init("https://nowpay.lk/api/v1/reloads");
curl_setopt_array($curl, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false, CURLOPT_CONNECTTIMEOUT => 5, CURLOPT_TIMEOUT => 15,
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . $key, "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode($order, JSON_THROW_ON_ERROR)
]);
$raw = curl_exec($curl);
$httpStatus = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($raw === false) { throw new RuntimeException("Network error: check the saved order reference before retrying"); }
$body = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if (isset($body["data"])) {
echo $body["data"]["reference"] . " " . $body["data"]["status"];
} else { echo $httpStatus . " " . ($body["error"]["code"] ?? "UNKNOWN_ERROR"); }
13. Key rotation, testing and support
- Create a separately labeled key per integration. Rotate by creating a new key, updating your server, checking GET /balance, and revoking the old key. Revocation stops new requests immediately; keep existing order references for reconciliation.
- Before release, validate enabled services, formats, current rates, insufficient-funds handling, error states and same-reference retries in your own controlled test environment. Read-only GET requests are the safe first live checks; arrange an intentional funded reload before testing a paid POST.
- Protect your own order-confirmation endpoint, use spend limits, queue requests below the rate limit, and reconcile your database with NowPay order references, actual debits and final statuses.
- For help, provide the NowPay reference, your client reference, time and error code. Never send the API key, password or PIN. API-key requests act on your retailer wallet; they cannot read another retailer’s orders.