සිල්ලර වෙළෙන්දාගේ API ඒකාබද්ධ කිරීමේ මාර්ගෝපදේශය
ඔබගේ වෙබ් අඩවිය, ජංගම යෙදුම, POS හෝ ව්යාපාරික පද්ධතිය NowPay වෙළෙන්දාගේ මුදල් පසුම්බිය සමඟ සම්බන්ධ කරන්න.
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 එකක හෝ රහස් කළමනාකරණ සේවාවක තබන්න. Browser JavaScript, බෙදාහරින Android/iOS යෙදුම්, Git, තිර රූප හෝ URL තුළ එය ඇතුළත් නොකරන්න.
- ඔබගේ backend එකේ පරිශීලකයාගේ අනන්යතාව සහ අවසර පරීක්ෂා කර සේවාව, ලබන්නා සහ මුදල වලංගු කර ගෙවීමට ඔහුගේ අනුමැතිය ලබාගන්න. ඕනෑම අයෙකුට ඔබගේ වෙළෙන්දාගේ ශේෂයෙන් වියදම් කළ හැකි අනාරක්ෂිත proxy එකක් විවෘත නොකරන්න.
- මුලින් ඔබගේ දත්ත ගබඩාවේ ඇණවුමක් සාදා එහි අනන්ය reference එක සහ සම්පූර්ණ ඉල්ලීම සුරකින්න. සැසඳීම සඳහා NowPay reference එක, අවසන් තත්ත්වය සහ සැබෑ අඩු කළ මුදල සටහන් කරන්න.
- API යතුර මඟින් පසුම්බියෙන් වියදම් කිරීමට අවසර ලැබේ. එක් එක් API රීලෝඩ් ඉල්ලීමට ගෙවීම් PIN එකක් ඉල්ලන්නේ නැත. වෙබ් අඩවියේ API යතුර නිර්මාණය කරන විට PIN එකෙන් තහවුරු කිරීම අවශ්යය.
3. අනන්යතාව තහවුරු කිරීම සහ පළමු ඉල්ලීම
HTTPS භාවිත කර සෑම ඉල්ලීමකම Authorization: Bearer <ඔබගේ යතුර> header එක යවන්න. X-API-Key: <ඔබගේ යතුර> ද සහාය දක්වයි. URL parameter හෝ JSON body තුළ ඇති යතුරකින් අනන්යතාව තහවුරු නොවේ. POST සඳහා Content-Type: application/json යවන්න.
උදාහරණවල 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 | සක්රිය දත්ත පැකේජ. operator පෙරහන විකල්පයකි; කුඩා හෝ විශාල අකුරු භාවිත කළ හැක. ලැබෙන පැකේජ id එක සුරැක යවන්න. |
| POST /reloads | prepaid, postpaid, data-pack, broadband හෝ dth ගෙවීමක් නිර්මාණය කරන්න. |
| GET /reloads/{reference} | ඔබගේ ඇණවුම NowPay reference එකෙන් හෝ ඔබ යැවූ 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 ගිණුම් අංකය. |
| amount | data-pack හැර අනිවාර්යය. දශම ස්ථාන දෙකක් දක්වා ඇති ධන මුදලක් decimal string ලෙස යවන්න. මුදල් ඒකකය operator හි face_currency අගයයි. |
| pack_id | data-pack සඳහා පමණක් අනිවාර්යය. එම operator සඳහා GET /packs හි සක්රිය id එකක් භාවිත කරන්න. සේවාදායකයා භාවිත කරන්නේ පැකේජයේ වත්මන් මිලය; ඔබ යවන amount එක නොවේ. |
| reference | අනිවාර්ය string එකකි: ASCII අකුරු, ඉලක්කම්, තිත්, underscores හෝ hyphens 1–64ක්. ඔබගේ ගිණුමේ නව ගෙවීමකට අනන්ය විය යුතුය. එකම ඉල්ලීම නැවත යැවීමට පමණක් නැවත භාවිත කරන්න. |
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"
}'
දත්ත පැකේජයේ 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: DHBB | මුලින් 0 ඇති ඉලක්කම් දහයක Dialog home-broadband/router අංකය. පිළිගත් රටේ කේත සහිත ආකෘති සාමාන්යකරණය කෙරේ. |
| dth: DTV | Dialog TV ගිණුම් අංකය: හරියටම ඉලක්කම් අටකි. |
| dth: DISHTV, SUNDIRECT | Dish TV / Sun Direct card අංකය: මුල් බින්දු ද ඇතුළුව හරියටම ඉලක්කම් එකොළහකි. |
| dth: D2H | Videocon D2h ගිණුම් අංකය: ඉලක්කම් හයේ සිට දොළහ දක්වා. |
7. මුදල්, කොමිස් සහ පසුම්බියෙන් අඩු වන මුදල
ශේෂය, face_amount, debit_amount සහ අනුපාත decimal strings ලෙස ලැබේ. ඔබගේ පද්ධතියේ decimal ගණනය භාවිත කර මුදල් සඳහා දශම ස්ථාන දෙකක් තබන්න. Binary floating-point වටකිරීම් මත රඳා නොසිටින්න.
DISCOUNT: පසුම්බියෙන් අඩු වන මුදල = මුහුණත අගය × (100 − commission_rate) ÷ 100. දශම ස්ථාන දෙකට half-up වටකිරීම යෙදේ. උදාහරණයක් පමණි: LKR 100 සඳහා 1% නම් අඩුවීම LKR 99කි.
MULTIPLIER: LKR පසුම්බි අඩුවීම = INR මුහුණත අගය × commission_rate. දශම ස්ථාන දෙකට half-up වටකිරීම යෙදේ. මෙහි 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 උදාහරණයක් පමණි. සැබෑ ශේෂ, අනුපාත, references සහ වේලාවන් වෙනස් වේ. created_at/completed_at ISO වේලාවන්ය. completed_at, operator_reference සහ message null විය හැක. balance සහ duplicate ඇත්තේ POST ප්රතිචාරයේය; GET ඇණවුම් ප්රතිචාරයේ නොවේ.
| ප්රතිචාර field එක | අර්ථය |
|---|---|
| reference / client_reference | NowPay නිර්මාණය කළ ඇණවුම් reference එක / ඔබ සුරැක යැවූ reference එක. |
| service / operator / package / target | සුරැකි සේවා enum අගය විශාල අකුරින්, operator කේතය, විකල්ප පැකේජ නම සහ සාමාන්යකරණය කළ ලබන්නා. |
| pricing_mode / face_currency | DISCOUNT හෝ MULTIPLIER සහ මුහුණත මුදල් ඒකකය LKR හෝ INR. |
| face_amount / commission_rate / debit_amount | සේවා මුහුණත අගය, යෙදූ වෙළෙන්දාගේ අනුපාතය සහ සැබෑ LKR පසුම්බි අඩුවීම. |
| status / message / operator_reference | සුරැකි ගෙවීම් තත්ත්වය, පැහැදිලි කිරීම සහ විකල්ප provider reference එක. |
| created_at / completed_at | නිර්මාණය කළ වේලාව සහ විකල්ප සම්පූර්ණ කළ වේලාව. |
| balance / duplicate | POST හි පමණක් ලැබෙන වත්මන් LKR ශේෂය / නැවත යැවූ එකම ගෙවීමක් ද යන්න. |
| error.code / error.message | ඉල්ලීම් දෝෂයක යන්ත්ර කේතය සහ පැහැදිලි කිරීම. ඇණවුමක් තිබේ නම් 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 එක කිසිසේත් වෙනස් නොකරන්න.
- GET සෙවීමට තාවකාලිකව 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 තබා රැඳී සිටින්න. |
| SUCCESS | NowPay හි සම්පූර්ණ වී ඇත. වත්මන් TM පිළිගැනීමේ ප්රතිපත්තිය අනුව පිළිගත් successful/accepted TM ප්රතිචාර වහාම සම්පූර්ණ වේ. |
| PENDING | Timeout හෝ අනපේක්ෂිත provider ප්රතිචාරයක් වැනි හේතුවකින් ප්රතිඵලය තහවුරු නැත. අඩු කළ මුදල රඳවා තබයි; දිගටම පැවතුණොත් සහාය අමතන්න. |
| FAILED | Provider පැහැදිලිව රීලෝඩ් එක ප්රතික්ෂේප කළේය. සුරැකි පසුම්බි අඩුවීම එක් වරක් ආපසු ලැබේ. |
| REFUNDED | වෙනම තහවුරු කළ අවලංගු කිරීමකින් සුරැකි අඩු කළ මුදල ආපසු ලැබුණි. |
| REJECTED | සමාලෝචනය සඳහා ප්රතික්ෂේප කර ඇත. මෙය පමණක් සිදුවීමෙන් මුදල් ආපසු ලැබෙන්නේ නැත. |
11. දෝෂ සහ ඉල්ලීම් සීමා
| HTTP / කේතය | කළ යුතු දේ |
|---|---|
| 400 INVALID_REFERENCE / INVALID_OPERATOR / INVALID_PACK / INVALID_TARGET / UNKNOWN_SERVICE / BAD_REQUEST | වලංගු නොවන field, අංක ආකෘතිය හෝ මුදල නිවැරදි කරන්න. දැනටමත් පිළිගත් ගෙවීමේ විස්තර එකම reference යටතේ වෙනස් නොකරන්න. |
| 401 UNAUTHORIZED | Header එක සහ සම්පූර්ණ යතුර පරීක්ෂා කරන්න. අවලංගු කළ යතුරකට හෝ ගිණුම් ආරක්ෂක අවලංගු කිරීමකට පසුව නව යතුරක් අවශ්ය වේ. |
| 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 වෙනත් ඉල්ලීමකට අදාළය. මුල් ඇණවුම සමඟ සසඳන්න; එහි විස්තර වෙනස් නොකරන්න. |
| 413 | JSON 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 පරීක්ෂා කළ පසුව පැරණි යතුර අවලංගු කරන්න. අවලංගු කිරීම නව ඉල්ලීම් වහාම නවතයි. පවතින ඇණවුම් references සැසඳීම සඳහා තබාගන්න.
- නිකුත් කිරීමට පෙර සක්රිය සේවා, අංක ආකෘති, වත්මන් අනුපාත, ශේෂය ප්රමාණවත් නොවීම, දෝෂ සහ එකම reference නැවත භාවිතය ඔබගේ පාලිත පරීක්ෂණ පරිසරයේ පරීක්ෂා කරන්න. සජීවීව පළමුව කියවීමට පමණක් ඇති GET භාවිත කරන්න. ගෙවීම් සහිත POST පරීක්ෂාවකට පෙර සැලසුම් කළ සැබෑ රීලෝඩ් එකක් සහ මුදල් සූදානම් කරගන්න.
- ඔබගේ order-confirmation endpoint ආරක්ෂා කරන්න, වියදම් සීමා යොදන්න, ඉල්ලීම් සීමාවට අඩුවෙන් queue කරන්න. ඔබගේ දත්ත ගබඩාවේ සටහන් NowPay references, සැබෑ අඩු කිරීම් සහ අවසන් තත්ත්ව සමඟ සසඳන්න.
- සහාය ලබාගැනීමට NowPay reference, ඔබගේ client reference, වේලාව සහ දෝෂ කේතය දෙන්න. API යතුර, මුරපදය හෝ PIN යවන්න එපා. API ඉල්ලීම් ඔබගේ වෙළෙන්දාගේ පසුම්බියට අදාළය; වෙනත් වෙළෙන්දෙකුගේ ඇණවුම් කියවිය නොහැක.