Docs  /  Getting started

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.

Base URL https://nobabpay.com Currency BDT Invoice lifetime 15 min Format JSON

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.

  1. Your server creates an invoicePOST amount, success_url and the customer details. You get an invoice_id and a payment_url back.
  2. The customer paysRedirect to payment_url. The page shows your wallet number, the exact amount and a countdown.
  3. The SMS app confirms itThe bKash/Nagad SMS that lands on your phone is forwarded to the gateway, which matches TrxID, amount and sender.
  4. You are told instantlyA signed webhook is posted to your server and the customer is redirected to success_url.

Quick start

Before you write code: create an account, add a brand (Admin → Brands) and copy its Brand Key — it looks like bk_xxxxxxxx. A payment can only be created when at least one wallet is active and can accept the amount.
  1. Copy your Brand KeyAdmin → Brands → Key. Keep it on the server, never in the browser.
  2. Create an invoicePOST /api/v1/create-payment.php with amount and success_url.
  3. Redirect the customerSend them to the returned payment_url.
  4. Verify on your success pagePOST /api/v1/verify-payment.php with the invoice_id. Trust this answer, not the URL.
  5. Optional: webhookAdd webhook_url to 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.

HTTP headerrequired
X-API-KEY: bk_live_1a2b3c4d5e6f7g8h
Content-Type: application/json

Create a payment

POST /api/v1/create-payment.php — JSON or form encoded.

FieldTypeRequiredNotes
amountnumberyesBDT, minimum 1, maximum 10,000,000. Two decimals allowed.
success_urlstringyesFull https:// URL the customer returns to after paying.
cancel_urlstringnoWhere to send the customer if they cancel.
webhook_urlstringnoOverrides the brand webhook for this invoice only.
customer_namestringnoShown on the checkout page and in the dashboard.
customer_emailstringnoMax 190 characters.
customer_phonestringnoMax 30 characters.
metadataobject / stringnoAnything you want back (order id, user id). Stored as JSON.

Response

JSON200 OK
{
  "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

bashcreate
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

PHPcreate
$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

JavaScriptcreate
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

Pythoncreate
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:

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.

The amount must match exactly. If the customer sends 501 instead of 500 the invoice stays pending and goes to review in the dashboard — you can still approve it there.

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"}.

JSON200 OK
{
  "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.

PHPon success_url
$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

statusMeaningWhat to do
pendingInvoice created, money not matched yet.Wait. Poll or rely on the webhook.
completedPayment matched and verified.Fulfil the order. Safe to credit once.
reviewSomething did not match (amount off, manual claim).Check Admin → Payments and approve or reject.
expiredNot paid within 15 minutes.Create a new invoice.
cancelledCustomer pressed cancel.Create a new invoice if they still want to pay.

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.

URLpublic
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.

POST to your webhook_urlJSON
{
  "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.

PHPwebhook receiver
$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
Node.jsExpress
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);
});
Webhooks can be retried only by you (Dashboard → Payments → Resend). Make the handler idempotent: the same 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.

Pythonbot.py
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.

Telegram requires HTTPS for 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:

  1. Create a deviceAdmin → Devices → Add device. Copy the Device Key (dk_…).
  2. Paste it in the appThe server is fixed to https://nobabpay.com; only the key changes per phone.
  3. Allow SMS accessAndroid asks once. Keep the phone on charge with internet.
  4. 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

PurposeEndpoint
Create payment (recommended)POST /api/v1/create-payment.php
Verify paymentPOST /api/v1/verify-payment.php
Checkout pageGET /pay/?id=INVOICE_ID
Payment linkGET /pay/link.php?s=CODE
Bot-compatible stylePOST /api/gateway.php?route=checkout · ?route=verify-payment
Alt (invoice-key) stylePOST /api/alt.php?action=create · ?action=verify
Device heartbeat / SMSPOST /api/device/ping.php · /api/device/sms.php
Short forms such as /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

HTTPmessageFix
401Invalid or missing API keyCheck X-API-KEY, and that the brand is active.
401account is disabled or expiredRenew the Premium plan of the account that owns the brand.
422amount must be a number >= 1Send a number, not a string with commas or a currency sign.
422success_url is requiredAdd a full https:// URL.
422No active wallet can accept this amountTurn on a wallet in Admin → Wallets or adjust its min/max.
404Invoice not foundWrong invoice_id, or it belongs to another brand.
429Too many requestsBack off — see rate limits below.

Rate limits

Go live checklist

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.