NowPay API

சில்லறை விற்பனையாளர் API இணைப்பு வழிகாட்டி

உங்கள் இணையதளம், மொபைல் செயலி, POS அல்லது வணிக அமைப்பை NowPay விற்பனையாளர் பணப்பையுடன் இணைக்கவும்.

API v1 · ஆங்கிலம், சிங்களம் மற்றும் தமிழ்

அடிப்படை URL: https://nowpay.lk/api/v1

API விசைகளை நிர்வகிக்கவும்

1. தொடங்குவதற்கு முன்

அங்கீகரிக்கப்பட்ட விற்பனையாளர் கணக்கு, நிர்வாகியால் செயல்படுத்தப்பட்ட Reseller API வசதி மற்றும் போதுமான பணப்பை இருப்பு தேவை. வாடிக்கையாளர் மற்றும் நிர்வாகி கணக்குகள் விற்பனையாளர் API விசைகளைப் பயன்படுத்த முடியாது.

இணையதளத்தில் Reseller API பகுதியைத் திறந்து விசைக்குப் பெயரிட்டு உங்கள் ஆறு இலக்கக் கட்டண PIN மூலம் உறுதிப்படுத்தவும். முழு விசை ஒருமுறை மட்டுமே காட்டப்படும்; உடனே நகலெடுக்கவும். அது hash வடிவில் மட்டுமே சேமிக்கப்படும். அதிகபட்சம் ஐந்து செயல்படும் விசைகளை வைத்திருக்கலாம். மொபைல் உள்நுழைவு token என்பது Reseller API விசை அல்ல.

முதலில் இருப்பு, சேவை வழங்குநர்கள் மற்றும் தொகுப்புகளைப் பெறும் வாசிப்புக்கான கோரிக்கைகளைப் பயன்படுத்தவும். நேரடி POST /reloads கோரிக்கை உண்மையான பணப்பைத் தொகையைச் செலவிட்டு உண்மையான ரீலோடை அனுப்பும். எல்லா placeholder மதிப்புகளையும் மாற்றி சரியான பெறுநரை உறுதிப்படுத்திய பிறகே அனுப்பவும். இந்த APIக்கு பொதுவான sandbox endpoint இல்லை.

2. உங்கள் செயலியை இணைக்கும் முறை

  • உங்கள் வாடிக்கையாளர் செயலி → உங்கள் அடையாளத்தைச் சரிபார்க்கும் backend → NowPay HTTPS API. ஆர்டரின் முடிவை மட்டும் செயலிக்குத் திருப்பி அனுப்பவும்.
  • NOWPAY_API_KEY விசையை சேவையக environment variable அல்லது secret manager இல் வைத்திருக்கவும். Browser JavaScript, வெளியிடப்படும் Android/iOS செயலி, Git, திரைப்பிடிப்பு அல்லது URL இல் சேர்க்க வேண்டாம்.
  • உங்கள் backend இல் பயனரின் அடையாளத்தையும் அனுமதியையும் சரிபார்த்து, சேவை, பெறுநர் மற்றும் தொகையைச் சரிபார்த்து அவரின் கட்டண ஒப்புதலைப் பெறவும். யாரும் உங்கள் விற்பனையாளர் பணப்பையைச் செலவிடக்கூடிய பாதுகாப்பற்ற proxyயை வழங்க வேண்டாம்.
  • முதலில் உங்கள் தரவுத்தளத்தில் ஆர்டரை உருவாக்கி அதன் தனித்துவமான reference மற்றும் முழுக் கோரிக்கையைச் சேமிக்கவும். கணக்குச் சரிபார்ப்பிற்காக NowPay reference, இறுதி நிலை மற்றும் உண்மையில் கழிக்கப்பட்ட தொகையைப் பதிவு செய்யவும்.
  • API விசை பணப்பையிலிருந்து செலவிட அனுமதி வழங்குகிறது. ஒவ்வொரு API ரீலோடுக்கும் கட்டண PIN கேட்கப்படாது. இணையதளத்தில் விசையை உருவாக்கும்போது PIN உறுதிப்படுத்தல் தேவை.

3. அங்கீகாரமும் முதல் கோரிக்கையும்

HTTPS பயன்படுத்தி ஒவ்வொரு கோரிக்கையிலும் Authorization: Bearer <உங்கள் விசை> header அனுப்பவும். X-API-Key: <உங்கள் விசை> என்பதும் ஆதரிக்கப்படுகிறது. URL parameter அல்லது JSON body இல் உள்ள விசையால் அங்கீகாரம் பெற முடியாது. POST கோரிக்கைகளுக்கு Content-Type: application/json அனுப்பவும்.

உதாரணங்கள் உங்கள் சேவையக environment இலிருந்து NOWPAY_API_KEYஐப் படிக்கின்றன. உண்மையான விசையை ஆவணத்தில் ஒட்டவோ உதவிக் குழுவுடன் பகிரவோ வேண்டாம்.

cURL கட்டளைகள் Bash/POSIX shell வடிவில் உள்ளன. Windows இல் Git Bash/WSL பயன்படுத்தவும் அல்லது Node.js/Python உதாரணங்களைப் பயன்படுத்தவும்.

பணப்பை இருப்பு API

GET /api/v1/balance நீங்கள் அனுப்பும் API விசைக்குரிய அங்கீகரிக்கப்பட்ட விற்பனையாளரின் தற்போதைய பணப்பை இருப்பைத் தருகிறது. request body அல்லது account ID தேவையில்லை. பிற கணக்குகளின் இருப்புகளும் உள் TM Hub/SMSlenz இருப்புகளும் இதில் இடம்பெறாது.

இந்த வாசிப்புக்கான கோரிக்கை பணப்பையிலிருந்து பணத்தைக் கழிக்காது; ரீலோட் அல்லது SMS அனுப்பாது. HTTP 200 பதிலில் success:true, இரு தசம இடங்களுள்ள string ஆக data.balance, LKR ஆக data.currency கிடைக்கும். உண்மையில் காலியான பணப்பைக்கு "0.00" வரும். பிழை ஏற்பட்டால் இருப்பு கிடைக்கவில்லை எனக் காட்டவும்; பூஜ்ஜியமாக மாற்ற வேண்டாம்.

உங்கள் பயனர் அடையாளத்தைச் சரிபார்க்கும் backend வழியாக அங்கீகரிக்கப்பட்ட பணியாளர்களுக்கு இருப்பைக் காட்டவும். API விசையை உங்கள் சேவையகத்தில் வைத்திருக்கவும். தேவைக்கேற்ப அல்லது திரை திறந்திருக்கும்போது நிமிடத்திற்கு ஒருமுறை புதுப்பிக்கவும். மற்ற API கோரிக்கைகளுடன் சேர்த்து ஒரு விசைக்கு நிமிடத்திற்கு 60 கோரிக்கைகள் என்ற வரம்பு பொருந்தும்.

இது அந்த நேரத்தின் இருப்பு மட்டுமே; ஒதுக்கப்பட்ட தொகையோ அடுத்த கட்டணம் வெற்றிபெறும் உத்தரவாதமோ அல்ல. தசமக் கணிதத்தைப் பயன்படுத்தவும். ஒவ்வொரு ஆர்டரிலும் சேவையகம் போதுமான பணம் உள்ளதா எனச் சரிபார்க்கும். POST /reloads பதிலில் மீதமுள்ள data.balance கிடைக்கும்; GET /reloads/{reference} பதிலில் அது கிடைக்காது.

அணுகல் விதிகள் மாறவில்லை: இல்லாத, தவறான அல்லது ரத்து செய்யப்பட்ட விசைக்கு 401; செயலற்ற கணக்கு அல்லது IP/HTTPS கட்டுப்பாட்டிற்கு 403; API வசதி முடக்கப்பட்டிருந்தால் 404; கோரிக்கை வரம்பை மீறினால் 429. புதுப்பிப்பு தோல்வியுற்றால் கடைசியாகப் பெற்ற இருப்பு பழையது எனக் காட்டவும்; முன்பு இருப்பு கிடைக்கவில்லை என்றால் கிடைக்கவில்லை எனக் காட்டவும்.

cURL மூலம் பணப்பை இருப்பைப் படிக்கவும்
curl --request GET "https://nowpay.lk/api/v1/balance" \
  --header "Authorization: Bearer $NOWPAY_API_KEY"
HTTP 200 இருப்புப் பதில் எடுத்துக்காட்டு
{
  "success": true,
  "data": {
    "balance": "12500.50",
    "currency": "LKR"
  }
}
Node.js சேவையகத்தில் இருப்பைப் படிக்கவும்
// 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. API முகவரிகள்

மேலுள்ள பாதைகள் அடிப்படை URLக்கு உரியவை. இந்த Reseller API இல் bulk reload, மின்சாரம்/நீர் கட்டணம், பணப்பையில் வரவு, API விசை உருவாக்கம் அல்லது webhook பதிவு endpoints இல்லை. விசைகளை இணையதளத்தில் நிர்வகிக்கவும்.

முறை மற்றும் பாதைசெயல்பாடு
GET /balanceவிற்பனையாளரின் பயன்படுத்தக்கூடிய LKR பணப்பை இருப்பு; வாசிப்புக்கு மட்டும்.
GET /operatorsதற்போதைய operator குறியீடுகள், பெயர்கள், செயல்பாட்டு நிலைகள், விலைக் கணக்கீட்டு முறைகள் மற்றும் விற்பனையாளர் விகிதங்கள்.
GET /packs?operator=DIALOGசெயலில் உள்ள data தொகுப்புகள். operator வடிகட்டி விருப்பத்திற்குரியது; பெரிய/சிறிய எழுத்து வேறுபாடு இல்லை. திரும்பும் தொகுப்பு idஐச் சேமித்து அனுப்பவும்.
POST /reloadsprepaid, postpaid, data-pack, broadband அல்லது dth கட்டணத்தை உருவாக்கவும்.
GET /reloads/{reference}உங்கள் ஆர்டரை அதன் NowPay reference அல்லது நீங்கள் அனுப்பிய client reference மூலம் தேடவும். referenceஐ URL-encode செய்யவும்.

5. ரீலோட் கோரிக்கையை உருவாக்குதல்

JSON objectஐ POST செய்யவும். எல்லா மொழிகளிலும் field பெயர்களும் enum மதிப்புகளும் ஆங்கிலத்திலேயே இருக்கும். தொடக்க பூஜ்ஜியங்கள் நீங்காமல் இருக்க தொலைபேசி மற்றும் கணக்கு எண்களை strings ஆக வைத்திருக்கவும்.

Fieldதேவை மற்றும் பொருள்
serviceவிருப்பத்திற்குரியது; அனுப்பாவிட்டால் prepaid பயன்படுத்தப்படும். prepaid, postpaid, data-pack, broadband அல்லது dth பயன்படுத்தவும்.
operatorகட்டாயம். GET /operators வழங்கும் DIALOG அல்லது DISHTV போன்ற NowPay குறியீட்டைப் பயன்படுத்தவும். 101 அல்லது 302 போன்ற TM provider எண்களை அனுப்ப வேண்டாம்.
numberகட்டாய string. தேர்ந்தெடுத்த சேவை/operatorக்கு ஏற்ற மொபைல், router அல்லது TV/card கணக்கு எண்.
amountdata-pack தவிர கட்டாயம். அதிகபட்சம் இரண்டு தசம இடங்களுடன் நேர்மறைத் தொகையை decimal string ஆக அனுப்பவும். நாணயம் operator வழங்கும் face_currency ஆகும்.
pack_iddata-packக்கு மட்டும் கட்டாயம். அதே operatorக்கான GET /packs வழங்கும் செயலில் உள்ள idஐப் பயன்படுத்தவும். சேவையகம் தற்போதைய தொகுப்பு விலையையே பயன்படுத்தும்; நீங்கள் அனுப்பும் amountஐ அல்ல.
referenceகட்டாய string: 1–64 ASCII எழுத்துகள், எண்கள், புள்ளிகள், underscores அல்லது hyphens. உங்கள் கணக்கில் ஒவ்வொரு புதிய கட்டணத்திற்கும் தனித்துவமாக இருக்க வேண்டும். அதே கோரிக்கையை மீண்டும் முயற்சிக்க மட்டும் அதையே பயன்படுத்தவும்.
cURL உடன் prepaid கோரிக்கை
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 தொகுப்புக்கான JSON body
{
  "service": "data-pack",
  "operator": "DIALOG",
  "number": "<CUSTOMER_MOBILE>",
  "pack_id": "<ID_FROM_GET_PACKS>",
  "reference": "YOUR_SAVED_PACK_ORDER_ID"
}
இந்திய DTHக்கான JSON body
{
  "service": "dth",
  "operator": "DISHTV",
  "number": "<11_DIGIT_CARD_NUMBER>",
  "amount": "100.00",
  "reference": "YOUR_SAVED_DTH_ORDER_ID"
}

6. சேவைகள், operator குறியீடுகள் மற்றும் பெறுநர் எண்கள்

பூஜ்ஜியங்கள் மட்டுமே உள்ள TV கணக்கு செல்லாது. தற்போதைய பட்டியலைப் பெற்று செயல்படும் operatorகள் மற்றும் தொகுப்புகளை மட்டும் பயன்படுத்தவும். பெறுநருக்கு NowPay கணக்கு தேவையில்லை.

சேவை / operatorபெறுநர் எண்
prepaid / postpaid: DIALOG, MOBITEL, HUTCH, AIRTELஅந்த operatorக்கு ஏற்ற இலங்கை மொபைல் எண் string. 07XXXXXXXX மற்றும் அதற்குச் சமமான +94/94 வடிவங்கள் ஒரே வடிவமாக மாற்றப்படும்.
data-pack: மேலுள்ள மொபைல் operatorகள், DHBBபொருத்தமான மொபைல் அல்லது home-broadband எண்; அதே operatorக்கான தொகுப்பைத் தேர்ந்தெடுக்கவும்.
broadband: DHBB0இல் தொடங்கும் பத்து இலக்க Dialog home-broadband/router எண். ஏற்கப்படும் நாட்டுக் குறியீட்டு வடிவங்கள் மாற்றப்படும்.
dth: DTVDialog TV கணக்கு: சரியாக எட்டு இலக்கங்கள்.
dth: DISHTV, SUNDIRECTDish TV / Sun Direct card: தொடக்க பூஜ்ஜியங்களையும் சேர்த்து சரியாக பதினொரு இலக்கங்கள்.
dth: D2HVideocon D2h கணக்கு: ஆறு முதல் பன்னிரண்டு இலக்கங்கள்.

7. தொகைகள், கமிஷன் மற்றும் பணப்பைக் கழிவு

இருப்பு, face_amount, debit_amount மற்றும் விகிதங்கள் decimal strings ஆக வழங்கப்படும். உங்கள் அமைப்பில் decimal கணக்கீட்டைப் பயன்படுத்தி பண மதிப்புகளை இரண்டு தசம இடங்களுடன் வைத்திருக்கவும். Binary floating-point roundingஐ நம்ப வேண்டாம்.

DISCOUNT: பணப்பைக் கழிவு = முகமதிப்பு × (100 − commission_rate) ÷ 100; இரண்டு தசம இடங்களுக்கு half-up rounding செய்யப்படும். விளக்க உதாரணம் மட்டும்: LKR 100க்கு 1% என்றால் LKR 99 கழிக்கப்படும்.

MULTIPLIER: LKR பணப்பைக் கழிவு = INR முகமதிப்பு × commission_rate; இரண்டு தசம இடங்களுக்கு half-up rounding செய்யப்படும். இங்கு commission_rate என்பது ஒரு INRக்கு LKR விகிதம்; சதவீதம் அல்ல. விளக்க உதாரணம் மட்டும்: INR 100க்கு 4.30 என்றால் LKR 430.

விலைகளை நிரந்தரமாகக் குறியீட்டில் எழுதாமல் GET /operators இலிருந்து pricing_mode, face_currency மற்றும் commission_rateஐப் பெறவும். விலைகளும் பரிவர்த்தனை வரம்புகளும் மாறலாம். Reseller quote endpoint இல்லை; சமர்ப்பிக்கும்போது தற்போதைய விலை பயன்படுத்தப்படும். உண்மையான கட்டணத்திற்கும் மீதமுள்ள இருப்பிற்கும் பதிலின் debit_amount மற்றும் balanceஐப் பயன்படுத்தவும்.

8. பதிலைச் சரியாகப் படித்தல்

புதிய ஆர்டருக்கு பொதுவாக HTTP 201 கிடைக்கும். அதே reference உடன் அதே கோரிக்கையை மீண்டும் அனுப்பினால் பழைய ஆர்டருடன் HTTP 200 மற்றும் duplicate:true கிடைக்கும். GET தேடலில் ஆர்டர் இருந்தால் அதன் கட்டண நிலை FAILED ஆனாலும் success:true கிடைக்கும்.

POST இல் FAILED அல்லது REJECTED ஆர்டருக்கு success:false வரலாம்; இருந்தாலும் data மற்றும் HTTP 201 இருக்கலாம். HTTP 200/201 அல்லது success:true மட்டும் சேவை வழங்கப்பட்டதற்கான உறுதி அல்ல. எப்போதும் data.statusஐப் பார்க்கவும்.

கீழுள்ள JSON விளக்கத்திற்கானது. உண்மையான இருப்பு, விகிதம், reference மற்றும் நேரங்கள் மாறும். created_at/completed_at என்பவை ISO நேரங்கள். completed_at, operator_reference மற்றும் message null ஆகலாம். balance மற்றும் duplicate ஆகியவை POST பதிலில் மட்டுமே; GET ஆர்டர் தேடலில் இல்லை.

பதில் fieldபொருள்
reference / client_referenceNowPay உருவாக்கிய ஆர்டர் reference / நீங்கள் சேமித்து அனுப்பிய reference.
service / operator / package / targetசேமிக்கப்பட்ட சேவை enum பெரிய எழுத்துகளில், operator குறியீடு, விருப்பத் தொகுப்புப் பெயர் மற்றும் மாற்றப்பட்ட பெறுநர் எண்.
pricing_mode / face_currencyDISCOUNT அல்லது MULTIPLIER; முகமதிப்பு நாணயம் LKR அல்லது INR.
face_amount / commission_rate / debit_amountசேவை முகமதிப்பு, பயன்படுத்தப்பட்ட விற்பனையாளர் விகிதம் மற்றும் உண்மையான LKR பணப்பைக் கழிவு.
status / message / operator_referenceசேமிக்கப்பட்ட கட்டண நிலை, விளக்கம் மற்றும் விருப்பமான provider reference.
created_at / completed_atஉருவாக்கிய நேரம் மற்றும் விருப்பமான நிறைவு நேரம்.
balance / duplicatePOST இல் மட்டும் தற்போதைய LKR இருப்பு / இது அதே கட்டணத்தின் மறுமுயற்சியா என்பது.
error.code / error.messageAPI கோரிக்கைப் பிழைக்கான இயந்திரக் குறியீடு மற்றும் விளக்கம். ஆர்டர் இருந்தால் dataஐயும் சரிபார்க்கவும்.
புதிய ஆர்டரின் விளக்கப் பதில்
{
  "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"
  }
}
கோரிக்கைப் பிழைக்கான உதாரணம்
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Insufficient balance. Required: LKR 99.00."
  }
}

9. இருமுறை பணம் கழியாத மறுமுயற்சிகள்

  • முதல் POSTக்கு முன் ஒரே தனித்துவமான reference மற்றும் முழுக் கோரிக்கையைச் சேமிக்கவும். உண்மையில் புதிய கட்டணத்திற்கு மட்டுமே புதிய reference பயன்படுத்தவும்.
  • Timeout, இணைப்புப் பிழை அல்லது உறுதியற்ற 5xx பதிலுக்குப் பிறகு சேமித்த referenceஐ GET மூலம் தேடவும். POST மீண்டும் அனுப்பினால் அதே reference, service, operator, பெறுநர், amount மற்றும் packஐ மாற்றாமல் பயன்படுத்தவும்.
  • தேடலில் தற்காலிகமாக 404 வந்தாலும் முதல் கோரிக்கை இன்னும் செயலாக்கத்தில் இருக்கலாம். காத்திருந்து மீண்டும் தேடவும் அல்லது அதே reference உடன் அதே POSTஐ அனுப்பவும். உறுதியற்ற நிலையைத் தவிர்க்க புதிய reference உருவாக்க வேண்டாம்.
  • ஏற்கனவே உள்ள referenceஇல் விவரங்களை மாற்றினால் 409 REFERENCE_CONFLICT கிடைக்கும். ஒரே கட்டணத்தை ஒரே விவரங்களுடன் ஒரே நேரத்தில் மீண்டும் அனுப்பினாலும் இரண்டாவது கழிவு ஏற்படாது.
  • PROCESSING/PENDINGக்கு வரம்புடைய polling மற்றும் அதிகரிக்கும் இடைவெளிகளைப் பயன்படுத்தவும்; உதாரணமாக 5, 10, 20, பின்னர் 60 விநாடிகள். இறுதி நிலையில் நிறுத்தவும். Polling கோரிக்கைகளும் வரம்பில் கணக்கிடப்படும். பதில் தாமதமானதால் மட்டும் தோல்வி எனக் கருதவோ உங்கள் வாடிக்கையாளருக்கு தானாக refund செய்யவோ வேண்டாம்.
சேமித்த referenceஐத் தேடவும்
curl --request GET "https://nowpay.lk/api/v1/reloads/YOUR_SAVED_ORDER_ID" \
  --header "Authorization: Bearer $NOWPAY_API_KEY"

10. ஆர்டர் நிலைகள்

GET status என்பது NowPay இல் சேமித்த ஆர்டரைப் படிக்கிறது; TMஐ நேரடியாக விசாரிப்பதில்லை. இந்த APIக்கு பொதுவான callback/webhook ஒப்பந்தம் இல்லை. உறுதியாகாத சேவைகளுக்கு ஊழியர்/provider மதிப்பாய்வு தேவைப்படலாம். நேரம் கடந்ததால் மட்டும் வழங்கப்பட்டது என ஊகிக்க வேண்டாம்.

நிலைபொருளும் செய்ய வேண்டியதும்
PROCESSINGபணப்பைக் கழிவு பதிவாகியுள்ளது; provider கோரிக்கை நடக்கிறது. அதே reference உடன் காத்திருக்கவும்.
SUCCESSNowPay இல் நிறைவு பெற்றது. தற்போதைய TM ஏற்றுக்கொள்ளல் கொள்கைப்படி அங்கீகரிக்கப்பட்ட successful/accepted TM பதில்கள் உடனடியாக நிறைவடைகின்றன.
PENDINGTimeout அல்லது எதிர்பாராத provider பதில் போன்ற காரணத்தால் முடிவு உறுதியாகவில்லை. கழிவு தொடரும்; நீடித்தால் உதவியை நாடவும்.
FAILEDProvider ரீலோடை வெளிப்படையாக நிராகரித்துள்ளார்; சேமித்த பணப்பைக் கழிவு ஒருமுறை திருப்பப்படும்.
REFUNDEDதனியாகச் சரிபார்க்கப்பட்ட ரத்து/refund மூலம் சேமித்த கழிவு திரும்பியது.
REJECTEDமதிப்பாய்விற்காக நிராகரிக்கப்பட்டது. நிராகரிப்பு மட்டும் பணத்தைத் திருப்பாது.

11. பிழைகள் மற்றும் கோரிக்கை வரம்புகள்

HTTP / குறியீடுசெய்ய வேண்டியது
400 INVALID_REFERENCE / INVALID_OPERATOR / INVALID_PACK / INVALID_TARGET / UNKNOWN_SERVICE / BAD_REQUESTதவறான field, எண் வடிவம் அல்லது தொகையைச் சரிசெய்யவும். ஏற்கனவே ஏற்றுக்கொள்ளப்பட்ட கட்டணத்தின் விவரங்களை அதே referenceஇல் மாற்ற வேண்டாம்.
401 UNAUTHORIZEDHeader மற்றும் முழு விசையைச் சரிபார்க்கவும். ரத்து செய்யப்பட்ட விசை அல்லது கணக்குப் பாதுகாப்பு ரத்துக்குப் பிறகு மாற்று விசை தேவை.
402 INSUFFICIENT_FUNDSவழக்கமான அங்கீகரிக்கப்பட்ட முறையில் பணப்பைக்கு நிதி சேர்க்கவும். மீண்டும் முயற்சிக்கும் முன் சேமித்த referenceஐச் சரிபார்க்கவும்.
403 ACCOUNT_INACTIVE / IP_NOT_ALLOWED / HTTPS_REQUIREDஅங்கீகரிக்கப்பட்ட விற்பனையாளர், அமைக்கப்பட்டிருந்தால் அனுமதிக்கப்பட்ட server IP மற்றும் HTTPS பயன்படுத்தவும். கணக்குக் கட்டுப்பாடுகளுக்கு உதவியை அணுகவும்.
404 NOT_FOUNDபாதை மற்றும் referenceஐச் சரிபார்க்கவும். ஆர்டர் இல்லாமை, வேறு விற்பனையாளருக்குச் சொந்தமாதல் அல்லது Reseller API முடக்கப்பட்டிருத்தல் காரணமாகலாம்.
405 METHOD_NOT_ALLOWED/reloads உருவாக்க GETக்கு பதில் POST பயன்படுத்தவும்.
409 REFERENCE_CONFLICTஉங்கள் reference வேறொரு கோரிக்கையைக் குறிக்கிறது. முதல் ஆர்டரைக் கணக்குச் சரிபார்க்கவும்; அதன் விவரங்களை மாற்ற வேண்டாம்.
413JSON bodyஐ 20 KB வரம்புக்குள் வைக்கவும். Reseller endpointsக்கு கோப்புகளை upload செய்ய வேண்டாம்.
429 RATE_LIMITEDஒரு விசைக்கு நிமிடத்திற்கு 60 கோரிக்கைகள்; கூடுதல் பொதுவான வரம்புகளும் பொருந்தும். Retry-After இருந்தால் பின்பற்றி இடைவெளியை அதிகரிக்கவும்.
503 MAINTENANCE / MAINTENANCE_PREVIEW / SERVICE_DISABLED / OPERATOR_DISABLED / OPERATOR_NOT_CONFIGUREDபுதிய கோரிக்கைகளை நிறுத்தவும். மீண்டும் முயற்சிக்கும் முன் சேவை கிடைப்பையும் சேமித்த ஆர்டரையும் சரிபார்க்கவும்.
500 அல்லது படிக்க முடியாத / பிணையப் பதில்முடிவை உறுதியற்றதாகக் கருதவும்; மீண்டும் முயற்சிக்கும் முன் பழைய referenceஐத் தேடவும்.

12. சேவையக இணைப்புக் குறியீட்டு உதாரணங்கள்

இந்த உதாரணங்கள் உங்கள் அடையாளத்தைச் சரிபார்க்கும் backendக்கானவை; வாடிக்கையாளர் செயலிக்கானவை அல்ல. Placeholderகளை மாற்றி, NOWPAY_API_KEYஐப் பாதுகாப்பாக அமைத்து, POSTக்கு முன் ஆர்டரைச் சேமிக்கவும். இவை உங்கள் பயனர் உள்நுழைவு, தரவுத்தளம் அல்லது அனுமதி அமைப்பை உருவாக்குவதில்லை.

மறுமுயற்சியில் அதே சேமித்த ஆர்டரைப் பயன்படுத்தவும். தேவையான reference மற்றும் statusஐ மட்டும் log செய்யவும். இரகசிய விசைகளை மறைத்து வாடிக்கையாளரின் முழுக் கட்டண விவரங்களை log செய்யாமல் இருக்கவும். TLS சான்றிதழ் சரிபார்ப்பை முடக்க வேண்டாம்.

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 · நிலையான நூலகம்
# 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. விசை மாற்றம், சோதனை மற்றும் உதவி

  • ஒவ்வொரு இணைப்பிற்கும் தனிப் பெயருடைய விசையை உருவாக்கவும். புதிய விசையை உருவாக்கி serverஐப் புதுப்பித்து GET /balanceஐச் சரிபார்த்த பின் பழைய விசையை ரத்து செய்யவும். ரத்து புதிய கோரிக்கைகளை உடனே நிறுத்தும்; பழைய ஆர்டர் referenceகளை கணக்குச் சரிபார்ப்பிற்காக வைத்திருக்கவும்.
  • வெளியீட்டிற்கு முன் செயல்படும் சேவைகள், எண் வடிவங்கள், தற்போதைய விகிதங்கள், போதாத இருப்பு, பிழைகள் மற்றும் அதே-reference மறுமுயற்சிகளை உங்கள் கட்டுப்படுத்தப்பட்ட சோதனைச் சூழலில் சோதிக்கவும். முதல் நேரடி சோதனைகளுக்கு வாசிப்புக்கான GETகளைப் பயன்படுத்தவும். கட்டண POSTக்கு முன் திட்டமிட்ட உண்மையான ரீலோடையும் நிதியையும் ஏற்பாடு செய்யவும்.
  • உங்கள் order-confirmation endpointஐப் பாதுகாத்து, செலவு வரம்புகளை அமைத்து, கோரிக்கைகளை வரம்புக்குள் queue செய்யவும். உங்கள் தரவுத்தளத்தை NowPay referenceகள், உண்மையான கழிவுகள் மற்றும் இறுதி நிலைகளுடன் ஒப்பிடவும்.
  • உதவிக்கு NowPay reference, உங்கள் client reference, நேரம் மற்றும் பிழைக் குறியீட்டை வழங்கவும். API விசை, கடவுச்சொல் அல்லது PINஐ அனுப்ப வேண்டாம். API கோரிக்கைகள் உங்கள் விற்பனையாளர் பணப்பைக்கானவை; வேறு விற்பனையாளரின் ஆர்டர்களைப் படிக்க முடியாது.