Developer documentation
Add Nobab Pay to a website, an app or a Telegram bot in about ten minutes. You create an invoice, send the customer to the payment page, and the gateway marks it paid by itself when the money reaches your bKash / Nagad / Rocket / Upay number.
How it works
The money never passes through Nobab Pay. The customer sends it straight to the wallet number you added in the dashboard, and the gateway only reads the confirmation SMS from your Android phone and matches it to the invoice.
- Your server creates an invoicePOST amount, success_url and the customer details. You get an
invoice_idand apayment_urlback. - The customer paysRedirect to
payment_url. The page shows your wallet number, the exact amount and a countdown. - The SMS app confirms itThe bKash/Nagad SMS that lands on your phone is forwarded to the gateway, which matches TrxID, amount and sender.
- You are told instantlyA signed webhook is posted to your server and the customer is redirected to
success_url.
Quick start
bk_xxxxxxxx. A payment can only be created when at least one wallet is active and can accept the amount.- Copy your Brand KeyAdmin → Brands → Key. Keep it on the server, never in the browser.
- Create an invoice
POST /api/v1/create-payment.phpwithamountandsuccess_url. - Redirect the customerSend them to the returned
payment_url. - Verify on your success page
POST /api/v1/verify-payment.phpwith theinvoice_id. Trust this answer, not the URL. - Optional: webhookAdd
webhook_urlto get a signed POST the moment the invoice is paid.
Authentication
Every request is authenticated with the Brand Key. Send it in the X-API-KEY header (recommended). These alternatives are accepted as well: API-KEY, Authorization: Bearer <key>, or an api_key field in the body.
X-API-KEY: bk_live_1a2b3c4d5e6f7g8h Content-Type: application/json
- Keys are per brand, so one account can run several shops with separate invoices and webhooks.
- If a key leaks, delete the brand key in the dashboard and create a new one — old keys stop working immediately.
- A disabled or expired account gets 401 with a message saying so.
Create a payment
POST /api/v1/create-payment.php — JSON or form encoded.
| Field | Type | Required | Notes |
|---|---|---|---|
amount | number | yes | BDT, minimum 1, maximum 10,000,000. Two decimals allowed. |
success_url | string | yes | Full https:// URL the customer returns to after paying. |
cancel_url | string | no | Where to send the customer if they cancel. |
webhook_url | string | no | Overrides the brand webhook for this invoice only. |
customer_name | string | no | Shown on the checkout page and in the dashboard. |
customer_email | string | no | Max 190 characters. |
customer_phone | string | no | Max 30 characters. |
metadata | object / string | no | Anything you want back (order id, user id). Stored as JSON. |
Response
{
"status": true,
"message": "Payment created",
"invoice_id": "NP7K2M9QX4T1",
"payment_url": "https://nobabpay.com/pay/?id=NP7K2M9QX4T1",
"expires_at": "2026-11-16 22:41:07"
}
cURL
curl -X POST https://nobabpay.com/api/v1/create-payment.php \ -H "X-API-KEY: bk_live_1a2b3c4d5e6f7g8h" \ -H "Content-Type: application/json" \ -d '{ "amount": 500, "success_url": "https://myshop.com/thank-you", "webhook_url": "https://myshop.com/pay/webhook", "customer_name": "Karim", "customer_email": "karim@example.com", "metadata": {"order_id": "ORD-1042"} }'
PHP
$payload = [ 'amount' => 500, 'success_url' => 'https://myshop.com/thank-you?order=1042', 'webhook_url' => 'https://myshop.com/pay/webhook', 'customer_name' => 'Karim', 'metadata' => ['order_id' => 'ORD-1042'], ]; $ch = curl_init('https://nobabpay.com/api/v1/create-payment.php'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($payload), CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'X-API-KEY: bk_live_1a2b3c4d5e6f7g8h', 'Content-Type: application/json', ], ]); $res = json_decode(curl_exec($ch), true); curl_close($ch); // remember the invoice id so you can verify it later $_SESSION['invoice_id'] = $res['invoice_id']; header('Location: ' . $res['payment_url']); exit;
Node.js
const res = await fetch('https://nobabpay.com/api/v1/create-payment.php', { method: 'POST', headers: { 'X-API-KEY': process.env.NOBAB_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ amount: 500, success_url: 'https://myshop.com/thank-you', webhook_url: 'https://myshop.com/pay/webhook', metadata: { order_id: 'ORD-1042' }, }), }); const pay = await res.json(); if (!pay.status) throw new Error(pay.message); res.redirect(pay.payment_url); // Express: send the customer to the checkout
Python
import requests r = requests.post( "https://nobabpay.com/api/v1/create-payment.php", headers={"X-API-KEY": API_KEY}, json={ "amount": 500, "success_url": "https://myshop.com/thank-you", "webhook_url": "https://myshop.com/pay/webhook", "metadata": {"order_id": "ORD-1042"}, }, timeout=20, ) pay = r.json() print(pay["payment_url"])
Checkout page
payment_url looks like https://nobabpay.com/pay/?id=NP7K2M9QX4T1. It is a normal page, so you can:
- redirect to it (
window.location/header('Location: …')), or - embed it in a modal with
<iframe src="…">— it is responsive and works on mobile.
The page shows your wallet number, the exact amount to send, a live countdown and the payment status. When the SMS arrives it flips to verified and, after a short delay, sends the customer to success_url.
Verify a payment
Never trust success_url alone — the customer can open it by hand. Ask the gateway:
POST /api/v1/verify-payment.php with {"invoice_id":"NP7K2M9QX4T1"}.
{
"status": true,
"data": {
"invoice_id": "NP7K2M9QX4T1",
"status": "completed",
"amount": "500.00",
"paid_amount": "500.00",
"currency": "BDT",
"method": "bkash",
"trx_id": "8HX4KQ2LM",
"sender_number": "01XXXXXXXXX",
"customer_name": "Karim",
"metadata": { "order_id": "ORD-1042" },
"created_at": "2026-11-16 22:26:07",
"completed_at": "2026-11-16 22:27:31"
}
}
Consider the order paid only when data.status === "completed" and data.paid_amount equals the amount you charged.
$ch = curl_init('https://nobabpay.com/api/v1/verify-payment.php'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode(['invoice_id' => $_GET['invoice_id']]), CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-API-KEY: bk_live_1a2b3c4d5e6f7g8h', 'Content-Type: application/json'], ]); $v = json_decode(curl_exec($ch), true); curl_close($ch); if (($v['data']['status'] ?? '') === 'completed' && ($v['data']['paid_amount'] ?? '0') === '500.00') { // mark the order paid (once — store trx_id to avoid double credits) mark_order_paid($v['data']['metadata']['order_id'], $v['data']['trx_id']); }
Statuses
| status | Meaning | What to do |
|---|---|---|
pending | Invoice created, money not matched yet. | Wait. Poll or rely on the webhook. |
completed | Payment matched and verified. | Fulfil the order. Safe to credit once. |
review | Something did not match (amount off, manual claim). | Check Admin → Payments and approve or reject. |
expired | Not paid within 15 minutes. | Create a new invoice. |
cancelled | Customer pressed cancel. | Create a new invoice if they still want to pay. |
Payment links (no code)
No website? Create a link in Admin → Payment Links and share it. Open amounts let the customer type their own amount; fixed links are ready to send as-is.
https://nobabpay.com/pay/link.php?s=a1b2c3d4
Payments made through a link are verified exactly like API payments and show up in the same dashboard.
Webhooks
Pass webhook_url when you create the invoice (or set one per brand in Admin → Brands). The gateway POSTs JSON the moment the invoice is completed and keeps the delivery result in the dashboard.
{
"event": "payment.completed",
"data": {
"invoice_id": "NP7K2M9QX4T1",
"status": "completed",
"amount": "500.00",
"paid_amount": "500.00",
"trx_id": "8HX4KQ2LM",
"method": "bkash",
"metadata": { "order_id": "ORD-1042" }
}
}
Verify the signature
Every request carries X-Signature: hash_hmac('sha256', raw_body, brand_key). Compare it with the raw body — not with re-encoded JSON.
$raw = file_get_contents('php://input'); $sig = $_SERVER['HTTP_X_SIGNATURE'] ?? ''; if (!hash_equals(hash_hmac('sha256', $raw, BRAND_KEY), $sig)) { http_response_code(401); exit('bad signature'); } $ev = json_decode($raw, true); if (($ev['event'] ?? '') === 'payment.completed') { mark_order_paid($ev['data']['metadata']['order_id'], $ev['data']['trx_id']); } http_response_code(200); // answer fast, do heavy work in a queue
import crypto from 'node:crypto'; app.post('/pay/webhook', express.raw({ type: '*/*' }), (req, res) => { const sig = crypto .createHmac('sha256', process.env.NOBAB_KEY) .update(req.body) .digest('hex'); if (sig !== req.get('X-Signature')) return res.status(401).send('bad signature'); const ev = JSON.parse(req.body.toString()); if (ev.event === 'payment.completed') { fulfil(ev.data.metadata.order_id, ev.data.trx_id); } res.sendStatus(200); });
trx_id must never credit an order twice.Telegram bot
Typical flow: the bot asks for the amount, creates an invoice, sends the payment_url, then confirms the order when the webhook arrives. This example uses python-telegram-bot v21 and Flask for the webhook.
import os, hmac, hashlib, requests from telegram import Update from telegram.ext import Application, CommandHandler, MessageHandler, filters from flask import Flask, request, abort API_KEY = os.environ["NOBAB_KEY"] # bk_… BASE = "https://nobabpay.com" BOT = Application.builder().token(os.environ["BOT_TOKEN"]).build() web = Flask(__name__) async def start(update: Update, _): await update.message.reply_text("How much do you want to pay? (BDT)") async def amount(update: Update, _): try: taka = float(update.message.text) except ValueError: return await update.message.reply_text("Send a number, e.g. 500") r = requests.post(f"{BASE}/api/v1/create-payment.php", headers={"X-API-KEY": API_KEY}, json={ "amount": taka, "success_url": "https://t.me", "webhook_url": os.environ["WEBHOOK"], "metadata": {"chat_id": update.effective_chat.id}, }, timeout=20).json() if not r.get("status"): return await update.message.reply_text(f"❌ {r.get('message')}") await update.message.reply_text( f"Pay ৳{taka:.0f} here:\n{r['payment_url']}\n\nInvoice {r['invoice_id']}") BOT.add_handler(CommandHandler("start", start)) BOT.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, amount)) # --- webhook: the gateway tells the bot when money arrived --- @web.post("/nobab/webhook") def nobab_webhook(): raw = request.get_data() sig = request.headers.get("X-Signature", "") if not hmac.compare_digest(hmac.new(API_KEY.encode(), raw, hashlib.sha256).hexdigest(), sig): abort(401) ev = request.get_json() if ev["event"] == "payment.completed": d = ev["data"] BOT.bot.send_message( chat_id=d["metadata"]["chat_id"], text=f"✅ Payment received: ৳{d['paid_amount']}\nTrxID {d['trx_id']}") return "", 200
Run the bot with polling (BOT.run_polling()) and expose Flask on HTTPS for the webhook, or keep both in one process with a small ASGI setup.
setWebhook; success_url must also be a full https:// URL. A bare https://t.me is fine as a placeholder.Android app (SMS verification)
Automatic verification needs one Android phone with the SIM that receives the bKash/Nagad SMS. Install the app, then:
- Create a deviceAdmin → Devices → Add device. Copy the Device Key (
dk_…). - Paste it in the appThe server is fixed to
https://nobabpay.com; only the key changes per phone. - Allow SMS accessAndroid asks once. Keep the phone on charge with internet.
- Assign the walletAdmin → Wallets → pick the number → select this device.
Behind the scenes the app calls POST /api/device/ping.php (heartbeat) and POST /api/device/sms.php (one call per SMS) with the header X-Device-Key. Nothing else is needed on your side.
Base URLs
| Purpose | Endpoint |
|---|---|
| Create payment (recommended) | POST /api/v1/create-payment.php |
| Verify payment | POST /api/v1/verify-payment.php |
| Checkout page | GET /pay/?id=INVOICE_ID |
| Payment link | GET /pay/link.php?s=CODE |
| Bot-compatible style | POST /api/gateway.php?route=checkout · ?route=verify-payment |
| Alt (invoice-key) style | POST /api/alt.php?action=create · ?action=verify |
| Device heartbeat / SMS | POST /api/device/ping.php · /api/device/sms.php |
/api/payment/checkout or /payment/INVOICE need a rewrite rule in the web server. On hosts that ignore .htaccess (CyberPanel / OpenLiteSpeed) they return 404 — always call the .php URLs above.Errors
| HTTP | message | Fix |
|---|---|---|
401 | Invalid or missing API key | Check X-API-KEY, and that the brand is active. |
401 | account is disabled or expired | Renew the Premium plan of the account that owns the brand. |
422 | amount must be a number >= 1 | Send a number, not a string with commas or a currency sign. |
422 | success_url is required | Add a full https:// URL. |
422 | No active wallet can accept this amount | Turn on a wallet in Admin → Wallets or adjust its min/max. |
404 | Invoice not found | Wrong invoice_id, or it belongs to another brand. |
429 | Too many requests | Back off — see rate limits below. |
Rate limits
- Create payment: 120 requests per minute per brand.
- Verify: no hard limit, but poll no more than once every 3–4 seconds.
- Payment page: 300 requests per 10 minutes per IP.
- Invoice lifetime: 15 minutes by default.
Go live checklist
- Brand key is stored in an environment variable, not in the repo.
amountis calculated on the server from your own cart — never from a form field.success_urlverification is implemented and comparespaid_amount.- Webhook signature is checked against the raw body.
- Order fulfilment is idempotent (unique index on
trx_id). - A failed payment leaves the order unpaid and shows a retry button.
- Site and API are on HTTPS; the Android phone stays online.
FAQ
Why does /api/payment/checkout return 404?
That short URL depends on a server rewrite rule. Use /api/gateway.php?route=checkout — it is the same endpoint and always works.
Payment made, invoice still pending?
Either the amount did not match exactly, or the SMS never reached the gateway. Check Admin → SMS for the message, then Admin → Payments and approve it manually. Make sure the phone is online and the wallet is assigned to that device.
Can one person pay two orders with the same TrxID?
No. A TrxID can complete only one invoice, and blocked TrxIDs can never complete anything.
Do you support refunds?
The money lands in your own wallet, so refunds are between you and the customer — the gateway does not hold funds.
Is there a test mode?
No sandbox: invoices are real. Test with ৳1 from your own number and mark the order as test in your own system.
Need help with an integration? Open your dashboard and use the Support card, or send the invoice ID together with the request you made — we can read the API log.