NowPay API

Retailer API integration guide

Connect your own website, mobile app, POS or business system to your NowPay retailer wallet.

API v1 · English, Sinhala and Tamil

Base URL: https://nowpay.lk/api/v1

Manage API keys

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 pathWhat it does
GET /balanceAvailable retailer wallet balance in LKR; read-only.
GET /operatorsCurrent operator codes, names, enabled flags, pricing modes and retailer rates.
GET /packs?operator=DIALOGActive data packages; the optional operator filter is case-insensitive. Store and submit the returned package id.
POST /reloadsCreate 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.

FieldRequirement and meaning
serviceOptional; defaults to prepaid. Use prepaid, postpaid, data-pack, broadband or dth.
operatorRequired. Use a NowPay code from GET /operators, such as DIALOG or DISHTV; do not send TM provider numbers such as 101 or 302.
numberRequired string. Recipient mobile, router or TV/card account number matching the selected service/operator.
amountRequired except data-pack. Positive amount with up to two decimal places; send a decimal string. The currency is face_currency from the operator.
pack_idRequired 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.
referenceRequired 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 / operatorsRecipient
prepaid / postpaid: DIALOG, MOBITEL, HUTCH, AIRTELSri Lankan mobile string matching the operator. 07XXXXXXXX and equivalent +94/94 formats are normalized.
data-pack: mobile operators above, DHBBMatching mobile or home-broadband number; select a package for that same operator.
broadband: DHBBDialog home-broadband/router number, ten digits starting with 0; accepted country-code formats are normalized.
dth: DTVDialog TV account: exactly eight digits.
dth: DISHTV, SUNDIRECTDish TV / Sun Direct card: exactly eleven digits, including any leading zeroes.
dth: D2HVideocon 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 fieldMeaning
reference / client_referenceNowPay-generated order reference / the reference you saved and sent.
service / operator / package / targetStored service enum (uppercase), operator code, optional package name and normalized recipient.
pricing_mode / face_currencyDISCOUNT or MULTIPLIER; face-value currency LKR or INR.
face_amount / commission_rate / debit_amountService face value, applied retailer rate and actual LKR wallet deduction.
status / message / operator_referenceSaved payment state, readable explanation and optional provider reference.
created_at / completed_atCreation time and optional completion time.
balance / duplicatePOST-only current LKR balance / whether this was an idempotent replay.
error.code / error.messageMachine 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.

StatusMeaning and action
PROCESSINGThe wallet debit is recorded and the provider call is in progress. Keep the same reference and wait.
SUCCESSCompleted in NowPay. Under the current TM acceptance policy, recognized successful/accepted TM responses finish immediately.
PENDINGThe outcome is unconfirmed, for example after a timeout or unexpected provider response. Keep the debit; contact support if it persists.
FAILEDProvider explicitly rejected the reload; the stored wallet debit is refunded once.
REFUNDEDA separately verified cancellation/refund returned the stored debit.
REJECTEDRejected for review. Rejection alone does not refund the wallet.

11. Errors and rate limits

HTTP / codeWhat to do
400 INVALID_REFERENCE / INVALID_OPERATOR / INVALID_PACK / INVALID_TARGET / UNKNOWN_SERVICE / BAD_REQUESTFix 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 UNAUTHORIZEDCheck the header and full key. A revoked key or account security revocation needs a replacement key.
402 INSUFFICIENT_FUNDSFund your retailer wallet through the usual approved funding workflow, then check the saved reference before retrying.
403 ACCOUNT_INACTIVE / IP_NOT_ALLOWED / HTTPS_REQUIREDUse an approved retailer, the permitted server IP if configured, and HTTPS. Ask support to resolve account restrictions.
404 NOT_FOUNDCheck 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_ALLOWEDUse POST, not GET, to create /reloads.
409 REFERENCE_CONFLICTYour reference already identifies another payload. Reconcile the original order; do not change its details.
413Keep JSON requests below the 20 KB body limit; do not upload files to reseller endpoints.
429 RATE_LIMITEDLimit 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_CONFIGUREDPause new submissions. Check service availability and the saved order before any retry.
500 or unreadable/network responseTreat 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.