← DZPay

API Documentation

Accept bKash / Nagad / Rocket / Upay / Cellfin / mCash / Bangla QR payments on any website with one simple API. Create a payment, redirect the customer to the hosted payment page, and get an instant webhook when the money arrives.

Download: API-DOCUMENTATION.md

1. Authentication

Every merchant API call must include your API key in the API-KEY header. Get your key from Dashboard → API after logging in. Keep it secret — it is the only credential another site needs.

header

API-KEY: YOUR_API_KEY

2. Create a Payment

Creates a pending payment and returns the hosted payment page URL. Redirect your customer to payment_url — the DZPay page handles method selection, receiver number, TrxID verification and the success redirect.

Field	Type	Required	Description
cus_name	string	optional	Customer name — shown as “Invoice To” on the payment page.
cus_email	string	optional	Customer email.
amount	number	yes	Amount in Taka (integer). Must be ≥ the gateway minimum.
webhook_url	url	recommended	The gateway POSTs here when the payment completes.
success_url	url	recommended	Browser redirect after a successful payment.
cancel_url	url	optional	Browser redirect when the payment is canceled/expired.
cus_orderid	string	optional	Your own order reference, echoed back in verify/webhook data.

curl

curl -X POST https://pay.dzhost.shop/api/payment/create \
  -H "Content-Type: application/json" \
  -H "API-KEY: YOUR_API_KEY" \
  -d '{
    "cus_name": "Rahim Uddin",
    "cus_email": "rahim@example.com",
    "amount": 500,
    "webhook_url": "https://yoursite.com/api/payment/callback",
    "success_url": "https://yoursite.com/payment/success",
    "cancel_url": "https://yoursite.com/payment/cancel"
  }'

Response

json

{
  "status": true,
  "payment_url": "https://pay.dzhost.shop/payment/K7QM2XZ",
  "txn_id": "K7QM2XZ",
  "amount": 500,
  "expires_at": "2026-10-19T10:30:00.000Z"
}

3. Hosted Payment Page Flow

Your site calls /api/payment/create and redirects the customer to payment_url (https://pay.dzhost.shop/payment/<txn_id>).
The customer selects bKash / Nagad / Rocket / … and presses PAY.
DZPay shows the receiver number + Bengali instructions; the customer sends money from their mobile-banking app and submits the TrxID.
Verification is automatic — the merchant SIM's credit SMS (forwarded by the SMS Reader app) confirms the payment within seconds.
DZPay: (a) POSTs the webhook to your webhook_url, and (b) redirects the customer's browser to your success_url with ?payment=<txn_id>&status=success&transaction_id=<trx>.
On expiry/cancel the browser goes to cancel_url with ?payment=<txn_id>&status=cancel.

4. Payment Webhook

When a payment completes, the gateway POSTs the payment result to your webhook_url (query-string params + form-encoded body, 10s timeout, one automatic attempt — re-send manually from Dashboard → Payments if your server missed it). Always confirm with the Verify API before delivering your product — never trust the callback parameters alone.

webhook payload

// The gateway POSTs these params to your webhook_url
// (appended to the query string AND sent as form body):
payment=K7QM2XZ
transactionId=8F7A2B9C1D        // the Send Money TrxID
transaction_id=8F7A2B9C1D
paymentAmount=500
paymentFee=0
status=COMPLETED
method=bkash                    // bkash | nagad | rocket | upay | cellfin | mcash | banglaqr

// Example final webhook URL:
https://yoursite.com/api/payment/callback?payment=123&transactionId=8F7A2B9C1D&paymentAmount=500&paymentFee=0&status=COMPLETED&method=bkash

5. Verify a Transaction

Server-to-server confirmation. Pass either the gateway txn_id (e.g. K7QM2XZ) or the customer's Send Money TrxID. A response whose status equals COMPLETED means the money is confirmed.

curl

curl -X POST https://pay.dzhost.shop/api/payment/verify \
  -H "Content-Type: application/json" \
  -H "API-KEY: YOUR_API_KEY" \
  -d '{ "transaction_id": "K7QM2XZ" }'

Response (completed)

json

{
  "status": "COMPLETED",
  "transaction_id": "8F7A2B9C1D",
  "txn_id": "K7QM2XZ",
  "amount": 500,
  "method": "bkash",
  "sender_number": "01712345678",
  "cus_name": "Rahim Uddin",
  "cus_email": "rahim@example.com",
  "order_id": "",
  "completed_at": "2026-10-19T10:21:44.000Z",
  "created_at": "2026-10-19T10:15:02.000Z"
}

6. Payment Statuses

PENDINGCreated, waiting for the customer to pay / be verified.

COMPLETEDMoney confirmed — webhook fired, customer redirected to success_url.

FAILEDRejected by the admin or verification failed.

CANCELEDExpired (unpaid after the expiry window) or canceled.

7. Full Examples

Copy-paste integration for PHP and Node.js.

PHP (cURL)

php

<?php
// PHP integration example
$apiKey = "YOUR_API_KEY";

$ch = curl_init("https://pay.dzhost.shop/api/payment/create");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "API-KEY: $apiKey",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "cus_name"    => $customerName,
    "cus_email"   => $customerEmail,
    "amount"      => $amount,           // integer Taka
    "webhook_url" => "https://yoursite.com/api/payment/callback?payment=" . $orderId,
    "success_url" => "https://yoursite.com/payment/success",
    "cancel_url"  => "https://yoursite.com/payment/cancel",
  ]),
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!empty($res["status"])) {
  // Redirect the customer to the hosted payment page
  header("Location: " . $res["payment_url"]);
  exit;
}
echo "Payment init failed: " . ($res["message"] ?? "unknown error");

Node.js (fetch)

javascript

// Node.js integration example
const res = await fetch("https://pay.dzhost.shop/api/payment/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "API-KEY": process.env.DZPAY_API_KEY,
  },
  body: JSON.stringify({
    cus_name: customerName,
    cus_email: customerEmail,
    amount: 500,
    webhook_url: "https://yoursite.com/api/payment/callback?payment=" + orderId,
    success_url: "https://yoursite.com/payment/success",
    cancel_url: "https://yoursite.com/payment/cancel",
  }),
});
const data = await res.json();

if (data.status === true) {
  // Redirect the customer to the hosted payment page
  window.location.href = data.payment_url;
}

8. Errors & Limits

HTTP	Meaning
401	Missing / invalid API-KEY header.
400	Invalid amount or URLs (amount ≥ minimum, absolute http(s) URLs).
404	Transaction not found (verify).
429	Rate limit — max 30 create calls per minute per IP.

Unpaid payments expire after the configured window (default 15 minutes) and then report CANCELED.

Auto-verification (SMS Reader): install the SMS Reader Android app from the Dashboard → SMS App tab, log in with the gateway admin credentials (Server URL = https://pay.dzhost.shop) and every credit SMS on that SIM completes matching payments automatically — no manual work.