BG PAY BD Developer Docs

Getting started

Introduction

BG PAY BD lets you accept payments from Bangladeshi mobile wallets and other methods on your own website or app. You integrate once with a simple JSON API and get paid straight into your own accounts.

There are two ways to integrate. Both use the same Brand API Key and the same webhook format, so you can start with one and add the other later.

Keep your API key secret. Call the API only from your server. Never put the key in browser JavaScript, a mobile app or a public repository.
Getting started

Choose an integration

Use this table to pick the right integration for your product.

Web Checkout
Direct API
Payment page
Hosted by us. Your customer is redirected.
Your own page or app screen.
API calls
2: create, verify.
3 to 4: create, submit, status.
Customer enters TrxID
On our page.
On your page, then you call submit.
Result
Redirect to your success URL, plus webhook.
Submit response, status API, plus webhook.
Methods
Every method enabled on your brand.
Mobile wallets and Bangla QR.
Best for
Online shops, WordPress, quick launch.
Apps, custom checkout, full branding control.
Not sure? Start with Web Checkout. You can add the Direct API later without changing your account or your webhook.
Getting started

Authentication

Every request is authenticated with your Brand API Key. Find it in your dashboard under Brands. Each brand has its own key, and payments are created for that brand.

API-KEYheaderrequired
Your Brand API Key. This is the recommended way to authenticate.
Content-Typeheaderrequired
Always application/json when you send a JSON body.

The Direct API also accepts Authorization: Bearer YOUR_API_KEY. Avoid sending the key in the URL, because URLs end up in server logs.

Example headers
API-KEY: YOUR_API_KEYContent-Type: application/json
If your key is ever exposed, regenerate it in your dashboard right away. Old keys stop working immediately.
Getting started

Requests and responses

All endpoints live on your payment base URL. If your brand has its own subdomain, call the API on the base URL shown in your dashboard.

Base URL
https://bgpaybd.shop
  • Send HTTPS POST requests with a JSON body (application/json).
  • Every response is JSON.
  • Amounts are in BDT. Maximum per payment is 1,000,000.
  • A payment link or session stays valid for 10 minutes.
  • Base your code on the HTTP status code and the status fields, not on message text. Messages can change and may be in Bangla.

HTTP status codes

Code
Meaning
200
The request worked.
201
A Direct API payment was created.
202
A Direct API submit was verified and is being finalized. Poll the status API.
400
The request is invalid. Fix it and send it again.
401
The API key is missing or invalid (Direct API).
404
The API key is wrong (Web Checkout) or the payment was not found.
409
A conflict, such as a reused idempotency key or an already completed payment.
429
Too many requests. Slow down and retry.
5xx
Something went wrong on our side. Retry with the same idempotency key.

Rate limits

Direct API calls are limited per brand, per minute. Going over the limit returns HTTP 429 with the error code rate_limited.

Endpoint
Per minute
direct/create
60
direct/methods
120
direct/submit
30
direct/status
240
direct/transaction/verify
120
Web Checkout

How it works

Your server creates a payment link, you redirect the customer to it, and we handle the rest. When the customer comes back, you verify the payment before delivering.

  1. Your serverCalls POST /api/payment/create with the amount and your return URLs.
  2. BG PAY BDReplies with a payment_url.
  3. Your serverRedirects the customer to that payment_url.
  4. CustomerChooses a method, pays, and enters the transaction ID.
  5. BG PAY BDVerifies the payment, sends the webhook (if set) and redirects the customer to your success_url.
  6. Your serverCalls POST /api/payment/verify and delivers the order when the status is COMPLETED.
Never trust the success URL alone. Anyone can type a URL into a browser. Always confirm with the Verify API before you deliver.
Web Checkout

Create a payment

Creates a payment link for one order. Redirect your customer to the returned payment_url.

Endpoint
POSThttps://bgpaybd.shop/api/payment/create

Body parameters

amountnumberrequired
Amount to collect in BDT. Must be greater than 0 and at most 1,000,000. Rounded to 2 decimals.
Example: 150 or 150.50
success_urlstringrequired
Full http(s) URL, up to 2000 characters, where the customer returns after paying.
cancel_urlstringrequired
Full http(s) URL, up to 2000 characters, where the customer returns if they cancel or the link expires.
cus_namestringoptional
Customer name. Up to 100 characters, HTML tags are removed.
Default: Default Name
cus_emailstringoptional
Customer email. Up to 150 characters, HTML tags are removed.
Default: default@gmail.com
metadataobjectoptional
Your own data, for example an order ID. It is returned by the Verify API. It must be a JSON object.
Example: {"order_id": "1001"}
webhook_urlstringoptional
Public http(s) URL that receives a signed server-to-server notification when the payment is recorded.
idempotency_keystringoptional
8 to 64 characters: letters, digits, _ or -. Retrying with the same key and amount while the first link is still unpaid and valid returns the same link. The same key with a different amount returns HTTP 409. You can also send it as the Idempotency-Key header.

Request

POST /api/payment/create
curl -X POST https://bgpaybd.shop/api/payment/create \ -H "API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "amount": 150, "cus_name": "John Doe", "cus_email": "john@gmail.com", "success_url": "https://yourdomain.com/success", "cancel_url": "https://yourdomain.com/cancel", "webhook_url": "https://yourdomain.com/webhook", "metadata": { "order_id": "1001" }, "idempotency_key": "order-1001-attempt-1" }'
<?php$payload = [ 'amount' => 150, 'cus_name' => 'John Doe', 'cus_email' => 'john@gmail.com', 'success_url' => 'https://yourdomain.com/success', 'cancel_url' => 'https://yourdomain.com/cancel', 'webhook_url' => 'https://yourdomain.com/webhook', 'metadata' => [ 'order_id' => '1001', ], 'idempotency_key' => 'order-1001-attempt-1',];$ch = curl_init('https://bgpaybd.shop/api/payment/create');curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_TIMEOUT => 20, CURLOPT_HTTPHEADER => ['API-KEY: YOUR_API_KEY', 'Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload),]);$response = json_decode(curl_exec($ch), true);curl_close($ch);if (($response['status'] ?? 0) == 1) { header('Location: ' . $response['payment_url']); exit;}
use Illuminate\Support\Facades\Http;$response = Http::withHeaders(['API-KEY' => 'YOUR_API_KEY']) ->timeout(20) ->post('https://bgpaybd.shop/api/payment/create', [ 'amount' => 150, 'cus_name' => 'John Doe', 'cus_email' => 'john@gmail.com', 'success_url' => 'https://yourdomain.com/success', 'cancel_url' => 'https://yourdomain.com/cancel', 'webhook_url' => 'https://yourdomain.com/webhook', 'metadata' => [ 'order_id' => '1001', ], 'idempotency_key' => 'order-1001-attempt-1', ]);$data = $response->json();return redirect()->away($data['payment_url']);
$response = wp_remote_post('https://bgpaybd.shop/api/payment/create', [ 'timeout' => 20, 'headers' => ['API-KEY' => 'YOUR_API_KEY', 'Content-Type' => 'application/json'], 'body' => wp_json_encode([ 'amount' => 150, 'cus_name' => 'John Doe', 'cus_email' => 'john@gmail.com', 'success_url' => 'https://yourdomain.com/success', 'cancel_url' => 'https://yourdomain.com/cancel', 'webhook_url' => 'https://yourdomain.com/webhook', 'metadata' => [ 'order_id' => '1001', ], 'idempotency_key' => 'order-1001-attempt-1', ]),]);if (is_wp_error($response)) { wp_die($response->get_error_message());}$data = json_decode(wp_remote_retrieve_body($response), true);wp_redirect($data['payment_url']);exit;
const response = await fetch('https://bgpaybd.shop/api/payment/create', { method: 'POST', headers: { 'API-KEY': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ amount: 150, cus_name: 'John Doe', cus_email: 'john@gmail.com', success_url: 'https://yourdomain.com/success', cancel_url: 'https://yourdomain.com/cancel', webhook_url: 'https://yourdomain.com/webhook', metadata: { order_id: '1001' }, idempotency_key: 'order-1001-attempt-1' }),});const data = await response.json();res.redirect(data.payment_url); // Express
import requestsresponse = requests.post( 'https://bgpaybd.shop/api/payment/create', headers={'API-KEY': 'YOUR_API_KEY'}, json={ 'amount': 150, 'cus_name': 'John Doe', 'cus_email': 'john@gmail.com', 'success_url': 'https://yourdomain.com/success', 'cancel_url': 'https://yourdomain.com/cancel', 'webhook_url': 'https://yourdomain.com/webhook', 'metadata': { 'order_id': '1001', }, 'idempotency_key': 'order-1001-attempt-1', }, timeout=20,)data = response.json()payment_url = data['payment_url'] # redirect your customer here
import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;// Java 15+ (text block)String json = """ { "amount": 150, "cus_name": "John Doe", "cus_email": "john@gmail.com", "success_url": "https://yourdomain.com/success", "cancel_url": "https://yourdomain.com/cancel", "webhook_url": "https://yourdomain.com/webhook", "metadata": { "order_id": "1001" }, "idempotency_key": "order-1001-attempt-1" }""";HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://bgpaybd.shop/api/payment/create")) .header("API-KEY", "YOUR_API_KEY") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build();HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString());System.out.println(response.body());
using System.Net.Http;using System.Net.Http.Json;var client = new HttpClient();client.DefaultRequestHeaders.Add("API-KEY", "YOUR_API_KEY");var response = await client.PostAsJsonAsync("https://bgpaybd.shop/api/payment/create", new{ amount = 150, cus_name = "John Doe", cus_email = "john@gmail.com", success_url = "https://yourdomain.com/success", cancel_url = "https://yourdomain.com/cancel", webhook_url = "https://yourdomain.com/webhook", metadata = new { order_id = "1001" }, idempotency_key = "order-1001-attempt-1"});var body = await response.Content.ReadAsStringAsync();Console.WriteLine(body);
package mainimport (	"bytes"	"fmt"	"io"	"net/http")func main() {	payload := []byte(`{ "amount": 150, "cus_name": "John Doe", "cus_email": "john@gmail.com", "success_url": "https://yourdomain.com/success", "cancel_url": "https://yourdomain.com/cancel", "webhook_url": "https://yourdomain.com/webhook", "metadata": { "order_id": "1001" }, "idempotency_key": "order-1001-attempt-1"}`)	req, _ := http.NewRequest("POST", "https://bgpaybd.shop/api/payment/create", bytes.NewBuffer(payload))	req.Header.Set("API-KEY", "YOUR_API_KEY")	req.Header.Set("Content-Type", "application/json")	res, err := http.DefaultClient.Do(req)	if err != nil {	panic(err)	}	defer res.Body.Close()	body, _ := io.ReadAll(res.Body)	fmt.Println(string(body))}

Response

200 OK
{ "status": 1, "message": "Payment Link", "payment_url": "https://bgpaybd.shop/payment/ABC1234"}

Redirect the customer to the exact payment_url you receive. If your brand has its own subdomain, the host already includes it. On failure you get "status": 0 and a message, see Errors.

Web Checkout

Redirect and return URL

After the payment, we send the customer back to your success_url (or cancel_url) and add these query parameters. Any query string already in your URL is kept, and a fragment (the part after #) is removed.

transactionIdstringrequired
Use this to call the Verify API.
Example: OVKPXW165414
paymentMethodstringoptional
Method the customer used. Empty when the customer cancelled or the link expired.
Example: bkash
paymentAmountstringoptional
Amount of the order, with three decimals.
Example: 150.000
paymentFeestringoptional
Fee charged, if any.
Example: 0
statusstringrequired
completed, pending (waiting for confirmation or manual review) or failed (cancelled, expired or closed).
Example return URL
https://yourdomain.com/success?transactionId=OVKPXW165414&paymentMethod=bkash&paymentAmount=150.000&paymentFee=0&status=completed
Web Checkout

Verify a payment

Call this from your server when the customer lands on your success_url, and again whenever you need the latest status. Only transactions created by your own account can be verified.

Endpoint
POSThttps://bgpaybd.shop/api/payment/verify
transaction_idstringrequired
The transactionId from your success URL or webhook.
Example: OVKPXW165414

Request

POST /api/payment/verify
curl -X POST https://bgpaybd.shop/api/payment/verify \ -H "API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "transaction_id": "OVKPXW165414" }'
<?php$payload = [ 'transaction_id' => 'OVKPXW165414',];$ch = curl_init('https://bgpaybd.shop/api/payment/verify');curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_TIMEOUT => 20, CURLOPT_HTTPHEADER => ['API-KEY: YOUR_API_KEY', 'Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload),]);$response = json_decode(curl_exec($ch), true);curl_close($ch);if (($response['status'] ?? '') === 'COMPLETED' && abs((float) $response['amount'] - 150.00) < 0.01) { markOrderPaid($response['transaction_id']); // your code}
use Illuminate\Support\Facades\Http;$response = Http::withHeaders(['API-KEY' => 'YOUR_API_KEY']) ->timeout(20) ->post('https://bgpaybd.shop/api/payment/verify', [ 'transaction_id' => 'OVKPXW165414', ]);$data = $response->json();if (($data['status'] ?? '') === 'COMPLETED' && abs((float) $data['amount'] - 150.00) < 0.01) { // mark the order as paid (once)}
$response = wp_remote_post('https://bgpaybd.shop/api/payment/verify', [ 'timeout' => 20, 'headers' => ['API-KEY' => 'YOUR_API_KEY', 'Content-Type' => 'application/json'], 'body' => wp_json_encode([ 'transaction_id' => 'OVKPXW165414', ]),]);if (is_wp_error($response)) { wp_die($response->get_error_message());}$data = json_decode(wp_remote_retrieve_body($response), true);if (($data['status'] ?? '') === 'COMPLETED' && abs((float) $data['amount'] - 150.00) < 0.01) { // mark the order as paid (once)}
const response = await fetch('https://bgpaybd.shop/api/payment/verify', { method: 'POST', headers: { 'API-KEY': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ transaction_id: 'OVKPXW165414' }),});const data = await response.json();if (data.status === 'COMPLETED' && Math.abs(Number(data.amount) - 150) < 0.01) { await markOrderPaid(data.transaction_id); // your code}
import requestsresponse = requests.post( 'https://bgpaybd.shop/api/payment/verify', headers={'API-KEY': 'YOUR_API_KEY'}, json={ 'transaction_id': 'OVKPXW165414', }, timeout=20,)data = response.json()if data.get('status') == 'COMPLETED' and abs(float(data['amount']) - 150.0) < 0.01: mark_order_paid(data['transaction_id']) # your code
import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;// Java 15+ (text block)String json = """ { "transaction_id": "OVKPXW165414" }""";HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://bgpaybd.shop/api/payment/verify")) .header("API-KEY", "YOUR_API_KEY") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build();HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString());System.out.println(response.body());
using System.Net.Http;using System.Net.Http.Json;var client = new HttpClient();client.DefaultRequestHeaders.Add("API-KEY", "YOUR_API_KEY");var response = await client.PostAsJsonAsync("https://bgpaybd.shop/api/payment/verify", new{ transaction_id = "OVKPXW165414"});var body = await response.Content.ReadAsStringAsync();Console.WriteLine(body);
package mainimport (	"bytes"	"fmt"	"io"	"net/http")func main() {	payload := []byte(`{ "transaction_id": "OVKPXW165414"}`)	req, _ := http.NewRequest("POST", "https://bgpaybd.shop/api/payment/verify", bytes.NewBuffer(payload))	req.Header.Set("API-KEY", "YOUR_API_KEY")	req.Header.Set("Content-Type", "application/json")	res, err := http.DefaultClient.Do(req)	if err != nil {	panic(err)	}	defer res.Body.Close()	body, _ := io.ReadAll(res.Body)	fmt.Println(string(body))}

Response

200 OK
{ "cus_name": "John Doe", "cus_email": "john@gmail.com", "amount": "150.000", "transaction_id": "OVKPXW165414", "metadata": "{\"order_id\":\"1001\"}", "payment_method": "bkash", "status": "COMPLETED"}

amount is a string with three decimals, so compare it as a number. metadata is a JSON-encoded string, decode it before use. payment_method is empty until a payment is recorded.

Status values

status
Meaning
What to do
COMPLETED
Payment received and confirmed.
Deliver the order. Also check that amount matches your order.
PENDING
Payment recorded, waiting for confirmation or manual review.
Wait. Do not deliver yet. Verify again later or wait for the webhook.
ERROR
No completed payment: not finished yet, cancelled, or the link expired.
Do not deliver. While the 10 minute link is valid the customer may still pay, so treat it as final only after expiry.

If the ID is unknown for your account, the response is "status": 0 with a message.

Web Checkout

Errors

Failed requests return JSON with "status": 0 and a message.

400 Bad Request
{ "status": 0, "message": "Your request is invalid."}
HTTP
When it happens
What to do
400
The endpoint is not create or verify, the amount is missing or out of range, success_url or cancel_url is missing or invalid, webhook_url is invalid, or idempotency_key has the wrong format.
Fix the request and send it again.
403
The request was sent to the wrong brand subdomain.
Use the base URL shown in your dashboard.
404
The API-KEY header is missing, wrong, or belongs to a deleted brand.
Check your Brand API Key.
409
The idempotency_key was already used with a different amount.
Use a new key for a new amount.
500
The payment link could not be created.
Retry with the same idempotency_key.
200
Response has "status": "error" when metadata is not a JSON object.
Send metadata as a JSON object.
Direct API

How it works

With the Direct API you control the whole payment screen. We give you the receiver details and the exact amount to send, your customer pays from their wallet, and you submit the wallet TrxID so we can verify it against the payment SMS.

  1. Your serverCalls POST /api/direct/create with the amount. You get a payment_id and a methods list.
  2. Your serverShows the receiver number (or QR code) and amount_to_send on your own page.
  3. CustomerSends the money from their wallet and gets a wallet TrxID.
  4. Your serverCalls POST /api/direct/submit with that trx_id.
  5. BG PAY BDMatches the TrxID with the received payment SMS and completes the payment.
  6. Your serverDelivers when the status is COMPLETED and the amount matches your order.
The payment SMS is read by the Payment Receiver App on your phone. If the SMS has not arrived yet, submit returns transaction_not_found. Retry after a few seconds. See Receiver app.
The customer must send exactly amount_to_send from the method they chose. It already includes any fee.
Direct API

Create a payment

Creates a payment and returns the methods your customer can pay with. A payment stays open for 10 minutes.

Endpoint
POSThttps://bgpaybd.shop/api/direct/create

Body parameters

amountnumberrequired
Amount to collect in BDT. Greater than 0 and at most 1,000,000. Rounded to 2 decimals.
order_idstringoptional
Your own reference. Letters, digits and _ - . :, up to 64 characters. You can look the payment up by it later.
cus_namestringoptional
Customer name. Up to 100 characters.
Default: Default Name
cus_emailstringoptional
Customer email. Up to 150 characters.
Default: default@gmail.com
cus_phonestringoptional
Customer phone. Digits and + only, up to 20 characters.
metadataobjectoptional
Your own data as a JSON object. It is returned in every response for this payment.
webhook_urlstringoptional
Public http(s) URL that receives a signed notification when the payment completes. See Webhooks.
success_urlstringoptional
Only needed for the hosted page fallback. If you send both success_url and cancel_url, the response also contains a payment_url.
cancel_urlstringoptional
See success_url.
idempotency_keystringoptional
8 to 64 characters: letters, digits, _ or -. The same key returns the same open payment. A different amount with the same key returns HTTP 409.

Request

POST /api/direct/create
curl -X POST https://bgpaybd.shop/api/direct/create \ -H "API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "amount": 500, "order_id": "ORD-1001", "cus_name": "John Doe", "cus_email": "john@gmail.com", "cus_phone": "01700000000", "metadata": { "cart_id": "88" }, "webhook_url": "https://yourdomain.com/webhook", "idempotency_key": "ORD-1001-attempt-1" }'
<?php$payload = [ 'amount' => 500, 'order_id' => 'ORD-1001', 'cus_name' => 'John Doe', 'cus_email' => 'john@gmail.com', 'cus_phone' => '01700000000', 'metadata' => [ 'cart_id' => '88', ], 'webhook_url' => 'https://yourdomain.com/webhook', 'idempotency_key' => 'ORD-1001-attempt-1',];$ch = curl_init('https://bgpaybd.shop/api/direct/create');curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_TIMEOUT => 20, CURLOPT_HTTPHEADER => ['API-KEY: YOUR_API_KEY', 'Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload),]);$response = json_decode(curl_exec($ch), true);curl_close($ch);$paymentId = $response['payment_id'];$methods = $response['methods']; // show these to your customer
use Illuminate\Support\Facades\Http;$response = Http::withHeaders(['API-KEY' => 'YOUR_API_KEY']) ->timeout(20) ->post('https://bgpaybd.shop/api/direct/create', [ 'amount' => 500, 'order_id' => 'ORD-1001', 'cus_name' => 'John Doe', 'cus_email' => 'john@gmail.com', 'cus_phone' => '01700000000', 'metadata' => [ 'cart_id' => '88', ], 'webhook_url' => 'https://yourdomain.com/webhook', 'idempotency_key' => 'ORD-1001-attempt-1', ]);$data = $response->json();$paymentId = $data['payment_id'];$methods = $data['methods']; // show these to your customer
$response = wp_remote_post('https://bgpaybd.shop/api/direct/create', [ 'timeout' => 20, 'headers' => ['API-KEY' => 'YOUR_API_KEY', 'Content-Type' => 'application/json'], 'body' => wp_json_encode([ 'amount' => 500, 'order_id' => 'ORD-1001', 'cus_name' => 'John Doe', 'cus_email' => 'john@gmail.com', 'cus_phone' => '01700000000', 'metadata' => [ 'cart_id' => '88', ], 'webhook_url' => 'https://yourdomain.com/webhook', 'idempotency_key' => 'ORD-1001-attempt-1', ]),]);if (is_wp_error($response)) { wp_die($response->get_error_message());}$data = json_decode(wp_remote_retrieve_body($response), true);$paymentId = $data['payment_id'];$methods = $data['methods']; // show these to your customer
const response = await fetch('https://bgpaybd.shop/api/direct/create', { method: 'POST', headers: { 'API-KEY': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ amount: 500, order_id: 'ORD-1001', cus_name: 'John Doe', cus_email: 'john@gmail.com', cus_phone: '01700000000', metadata: { cart_id: '88' }, webhook_url: 'https://yourdomain.com/webhook', idempotency_key: 'ORD-1001-attempt-1' }),});const data = await response.json();const paymentId = data.payment_id;const methods = data.methods; // show these to your customer
import requestsresponse = requests.post( 'https://bgpaybd.shop/api/direct/create', headers={'API-KEY': 'YOUR_API_KEY'}, json={ 'amount': 500, 'order_id': 'ORD-1001', 'cus_name': 'John Doe', 'cus_email': 'john@gmail.com', 'cus_phone': '01700000000', 'metadata': { 'cart_id': '88', }, 'webhook_url': 'https://yourdomain.com/webhook', 'idempotency_key': 'ORD-1001-attempt-1', }, timeout=20,)data = response.json()payment_id = data['payment_id']methods = data['methods'] # show these to your customer
import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;// Java 15+ (text block)String json = """ { "amount": 500, "order_id": "ORD-1001", "cus_name": "John Doe", "cus_email": "john@gmail.com", "cus_phone": "01700000000", "metadata": { "cart_id": "88" }, "webhook_url": "https://yourdomain.com/webhook", "idempotency_key": "ORD-1001-attempt-1" }""";HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://bgpaybd.shop/api/direct/create")) .header("API-KEY", "YOUR_API_KEY") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build();HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString());System.out.println(response.body());
using System.Net.Http;using System.Net.Http.Json;var client = new HttpClient();client.DefaultRequestHeaders.Add("API-KEY", "YOUR_API_KEY");var response = await client.PostAsJsonAsync("https://bgpaybd.shop/api/direct/create", new{ amount = 500, order_id = "ORD-1001", cus_name = "John Doe", cus_email = "john@gmail.com", cus_phone = "01700000000", metadata = new { cart_id = "88" }, webhook_url = "https://yourdomain.com/webhook", idempotency_key = "ORD-1001-attempt-1"});var body = await response.Content.ReadAsStringAsync();Console.WriteLine(body);
package mainimport (	"bytes"	"fmt"	"io"	"net/http")func main() {	payload := []byte(`{ "amount": 500, "order_id": "ORD-1001", "cus_name": "John Doe", "cus_email": "john@gmail.com", "cus_phone": "01700000000", "metadata": { "cart_id": "88" }, "webhook_url": "https://yourdomain.com/webhook", "idempotency_key": "ORD-1001-attempt-1"}`)	req, _ := http.NewRequest("POST", "https://bgpaybd.shop/api/direct/create", bytes.NewBuffer(payload))	req.Header.Set("API-KEY", "YOUR_API_KEY")	req.Header.Set("Content-Type", "application/json")	res, err := http.DefaultClient.Do(req)	if err != nil {	panic(err)	}	defer res.Body.Close()	body, _ := io.ReadAll(res.Body)	fmt.Println(string(body))}

Response

201 Created
{ "success": true, "payment_id": "K7M2QXA", "transaction_id": "OVKPXW165414", "order_id": "ORD-1001", "status": "CREATED", "amount": 500, "currency": "BDT", "customer": { "name": "John Doe", "email": "john@gmail.com", "phone": "01700000000" }, "metadata": { "cart_id": "88" }, "created_at": "2026-11-04 14:10:00", "expires_in": 600, "expires_at": "2026-11-04 14:20:00", "methods": [ { "method": "bkash", "account_type": "personal", "receiver_number": "01700000000", "qr_image_url": "", "amount": 500, "fee": 0, "amount_to_send": 500, "min_amount": 0, "required_fields": [ "trx_id" ], "optional_fields": [ "sender_number" ] }, { "method": "banglaqr", "account_type": "personal", "receiver_number": "", "qr_image_url": "https://bgpaybd.shop/public/uploads/user/.../qr/....png", "amount": 500, "fee": 0, "amount_to_send": 500, "min_amount": 0, "required_fields": [ "trx_id" ], "optional_fields": [ "sender_number" ] } ]}

The methods list

methodstringrequired
Method key, for example bkash. Use it as method when you submit.
account_typestringrequired
personal, agent or payment. Use it as account_type when you submit.
receiver_numberstringrequired
The number your customer sends money to. Empty for banglaqr.
qr_image_urlstringoptional
Bangla QR only. Show this image so the customer can scan it.
amountnumberrequired
Your order amount.
feenumberrequired
Fee added for this method.
amount_to_sendnumberrequired
The exact amount the customer must send. Amount plus fee.
min_amountnumberrequired
Smallest amount this method accepts. 0 means no limit.
required_fieldsarrayrequired
Fields you must send to submit. Always ["trx_id"].
optional_fieldsarrayrequired
Extra fields you may send. sender_number adds one more check.

If a payment has no available method, methods is an empty list. Methods that your brand has not enabled, or that are below their minimum amount, are left out.

Direct API

Get methods

Returns the same payment object as create, with a fresh methods list. Use it if the customer reopens your payment screen.

Endpoint
POSThttps://bgpaybd.shop/api/direct/methods
payment_idstringrequired
The payment_id from create. You can also send transaction_id or order_id.
POST /api/direct/methods
curl -X POST https://bgpaybd.shop/api/direct/methods \ -H "API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "payment_id": "K7M2QXA" }'
<?php$payload = [ 'payment_id' => 'K7M2QXA',];$ch = curl_init('https://bgpaybd.shop/api/direct/methods');curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_TIMEOUT => 20, CURLOPT_HTTPHEADER => ['API-KEY: YOUR_API_KEY', 'Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload),]);$response = json_decode(curl_exec($ch), true);curl_close($ch);
const response = await fetch('https://bgpaybd.shop/api/direct/methods', { method: 'POST', headers: { 'API-KEY': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ payment_id: 'K7M2QXA' }),});const data = await response.json();
import requestsresponse = requests.post( 'https://bgpaybd.shop/api/direct/methods', headers={'API-KEY': 'YOUR_API_KEY'}, json={ 'payment_id': 'K7M2QXA', }, timeout=20,)data = response.json()

methods is only filled while the payment is CREATED. For any other state it is an empty list.

Direct API

Submit a TrxID

Call this after your customer has paid and entered the wallet TrxID. We check it against the received payment SMS, make sure the amount matches, and complete the payment.

Endpoint
POSThttps://bgpaybd.shop/api/direct/submit

Body parameters

payment_idstringrequired
The payment to complete. You can also send transaction_id or order_id.
methodstringrequired
The method the customer used, for example bkash. Must be one of the methods from create.
account_typestringoptional
personal, agent or payment. If you leave it out, the first available type for the method is used.
trx_idstringrequired
The wallet transaction ID. 6 to 30 letters or digits. Spaces are removed and the case is ignored.
sender_numberstringoptional
The customer's wallet number, 10 to 15 digits. An extra check.
customer_ipstringoptional
Your customer's IP address. Wrong attempts are counted per customer, so one customer's mistakes never block another.

Request

POST /api/direct/submit
curl -X POST https://bgpaybd.shop/api/direct/submit \ -H "API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "payment_id": "K7M2QXA", "method": "bkash", "account_type": "personal", "trx_id": "BK12AB34CD", "sender_number": "01800000000", "customer_ip": "203.0.113.10" }'
<?php$payload = [ 'payment_id' => 'K7M2QXA', 'method' => 'bkash', 'account_type' => 'personal', 'trx_id' => 'BK12AB34CD', 'sender_number' => '01800000000', 'customer_ip' => '203.0.113.10',];$ch = curl_init('https://bgpaybd.shop/api/direct/submit');curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_TIMEOUT => 20, CURLOPT_HTTPHEADER => ['API-KEY: YOUR_API_KEY', 'Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload),]);$response = json_decode(curl_exec($ch), true);curl_close($ch);if (($response['status'] ?? '') === 'COMPLETED') { // paid: check amount, then deliver (once)}
use Illuminate\Support\Facades\Http;$response = Http::withHeaders(['API-KEY' => 'YOUR_API_KEY']) ->timeout(20) ->post('https://bgpaybd.shop/api/direct/submit', [ 'payment_id' => 'K7M2QXA', 'method' => 'bkash', 'account_type' => 'personal', 'trx_id' => 'BK12AB34CD', 'sender_number' => '01800000000', 'customer_ip' => '203.0.113.10', ]);$data = $response->json();if (($data['status'] ?? '') === 'COMPLETED') { // paid: check amount, then deliver (once)}
$response = wp_remote_post('https://bgpaybd.shop/api/direct/submit', [ 'timeout' => 20, 'headers' => ['API-KEY' => 'YOUR_API_KEY', 'Content-Type' => 'application/json'], 'body' => wp_json_encode([ 'payment_id' => 'K7M2QXA', 'method' => 'bkash', 'account_type' => 'personal', 'trx_id' => 'BK12AB34CD', 'sender_number' => '01800000000', 'customer_ip' => '203.0.113.10', ]),]);if (is_wp_error($response)) { wp_die($response->get_error_message());}$data = json_decode(wp_remote_retrieve_body($response), true);if (($data['status'] ?? '') === 'COMPLETED') { // paid: check amount, then deliver (once)}
const response = await fetch('https://bgpaybd.shop/api/direct/submit', { method: 'POST', headers: { 'API-KEY': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ payment_id: 'K7M2QXA', method: 'bkash', account_type: 'personal', trx_id: 'BK12AB34CD', sender_number: '01800000000', customer_ip: '203.0.113.10' }),});const data = await response.json();if (data.status === 'COMPLETED') { // paid: check amount, then deliver (once)}
import requestsresponse = requests.post( 'https://bgpaybd.shop/api/direct/submit', headers={'API-KEY': 'YOUR_API_KEY'}, json={ 'payment_id': 'K7M2QXA', 'method': 'bkash', 'account_type': 'personal', 'trx_id': 'BK12AB34CD', 'sender_number': '01800000000', 'customer_ip': '203.0.113.10', }, timeout=20,)data = response.json()if data.get('status') == 'COMPLETED': pass # paid: check amount, then deliver (once)
import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;// Java 15+ (text block)String json = """ { "payment_id": "K7M2QXA", "method": "bkash", "account_type": "personal", "trx_id": "BK12AB34CD", "sender_number": "01800000000", "customer_ip": "203.0.113.10" }""";HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://bgpaybd.shop/api/direct/submit")) .header("API-KEY", "YOUR_API_KEY") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build();HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString());System.out.println(response.body());
using System.Net.Http;using System.Net.Http.Json;var client = new HttpClient();client.DefaultRequestHeaders.Add("API-KEY", "YOUR_API_KEY");var response = await client.PostAsJsonAsync("https://bgpaybd.shop/api/direct/submit", new{ payment_id = "K7M2QXA", method = "bkash", account_type = "personal", trx_id = "BK12AB34CD", sender_number = "01800000000", customer_ip = "203.0.113.10"});var body = await response.Content.ReadAsStringAsync();Console.WriteLine(body);
package mainimport (	"bytes"	"fmt"	"io"	"net/http")func main() {	payload := []byte(`{ "payment_id": "K7M2QXA", "method": "bkash", "account_type": "personal", "trx_id": "BK12AB34CD", "sender_number": "01800000000", "customer_ip": "203.0.113.10"}`)	req, _ := http.NewRequest("POST", "https://bgpaybd.shop/api/direct/submit", bytes.NewBuffer(payload))	req.Header.Set("API-KEY", "YOUR_API_KEY")	req.Header.Set("Content-Type", "application/json")	res, err := http.DefaultClient.Do(req)	if err != nil {	panic(err)	}	defer res.Body.Close()	body, _ := io.ReadAll(res.Body)	fmt.Println(string(body))}

Responses

200 OK - completed
{ "success": true, "payment_id": "K7M2QXA", "transaction_id": "OVKPXW165414", "order_id": "ORD-1001", "status": "COMPLETED", "amount": 500, "currency": "BDT", "customer": { "name": "John Doe", "email": "john@gmail.com", "phone": "01700000000" }, "metadata": { "cart_id": "88" }, "created_at": "2026-11-04 14:10:00", "expires_in": 600, "expires_at": "2026-11-04 14:20:00", "method": "bkash", "amount_paid": 500, "fee": 0, "trx_id": "BK12AB34CD", "paid_at": "2026-11-04 14:13:42"}

Repeating the same call for an already completed payment returns the same result with "already_completed": true, so it is safe to retry after a network error.

202 Accepted - finalizing
{ "success": true, "payment_id": "K7M2QXA", "status": "PROCESSING", "message": "Payment verified and is being finalized. Check the status API shortly."}

A 202 means the payment was verified and is being finalized. Poll the status API until it is COMPLETED.

If the wallet SMS has not reached the system yet, submit fails with transaction_not_found. Wait a few seconds and try again. Wrong attempts are limited: 5 per payment and 15 per customer, then a 10 minute pause (too_many_attempts).
Direct API

Payment status

Returns the current state of a payment. Use it to poll after a 202, and as your source of truth before delivering.

Endpoint
POSThttps://bgpaybd.shop/api/direct/status
payment_idstringrequired
Send one of payment_id, transaction_id or order_id. When you use order_id, the latest payment with that reference is returned.
POST /api/direct/status
curl -X POST https://bgpaybd.shop/api/direct/status \ -H "API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "payment_id": "K7M2QXA" }'
<?php$payload = [ 'payment_id' => 'K7M2QXA',];$ch = curl_init('https://bgpaybd.shop/api/direct/status');curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_TIMEOUT => 20, CURLOPT_HTTPHEADER => ['API-KEY: YOUR_API_KEY', 'Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload),]);$response = json_decode(curl_exec($ch), true);curl_close($ch);
const response = await fetch('https://bgpaybd.shop/api/direct/status', { method: 'POST', headers: { 'API-KEY': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ payment_id: 'K7M2QXA' }),});const data = await response.json();
import requestsresponse = requests.post( 'https://bgpaybd.shop/api/direct/status', headers={'API-KEY': 'YOUR_API_KEY'}, json={ 'payment_id': 'K7M2QXA', }, timeout=20,)data = response.json()
200 OK
{ "success": true, "payment_id": "K7M2QXA", "transaction_id": "OVKPXW165414", "order_id": "ORD-1001", "status": "COMPLETED", "amount": 500, "currency": "BDT", "customer": { "name": "John Doe", "email": "john@gmail.com", "phone": "01700000000" }, "metadata": { "cart_id": "88" }, "created_at": "2026-11-04 14:10:00", "expires_in": 600, "expires_at": "2026-11-04 14:20:00", "method": "bkash", "amount_paid": 500, "fee": 0, "trx_id": "BK12AB34CD", "paid_at": "2026-11-04 14:13:42"}

method, amount_paid, fee, trx_id and paid_at appear once the payment is completed. Deliver goods only when status is COMPLETED and amount matches your order.

Direct API

Verify a transaction

Look up a wallet TrxID directly, without a payment ID. Useful for support tools and for checking a TrxID a customer sends you.

Endpoint
POSThttps://bgpaybd.shop/api/direct/transaction/verify
trx_idstringrequired
The wallet transaction ID.
amountnumberoptional
Your order amount. When you send it, the response includes amount_match.
POST /api/direct/transaction/verify
curl -X POST https://bgpaybd.shop/api/direct/transaction/verify \ -H "API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "trx_id": "BK12AB34CD", "amount": 500 }'
<?php$payload = [ 'trx_id' => 'BK12AB34CD', 'amount' => 500,];$ch = curl_init('https://bgpaybd.shop/api/direct/transaction/verify');curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_TIMEOUT => 20, CURLOPT_HTTPHEADER => ['API-KEY: YOUR_API_KEY', 'Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload),]);$response = json_decode(curl_exec($ch), true);curl_close($ch);
const response = await fetch('https://bgpaybd.shop/api/direct/transaction/verify', { method: 'POST', headers: { 'API-KEY': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ trx_id: 'BK12AB34CD', amount: 500 }),});const data = await response.json();
import requestsresponse = requests.post( 'https://bgpaybd.shop/api/direct/transaction/verify', headers={'API-KEY': 'YOUR_API_KEY'}, json={ 'trx_id': 'BK12AB34CD', 'amount': 500, }, timeout=20,)data = response.json()
200 OK - found
{ "success": true, "found": true, "status": "COMPLETED", "trx_id": "BK12AB34CD", "payment_id": "K7M2QXA", "transaction_id": "OVKPXW165414", "method": "bkash", "amount": 500, "amount_paid": 500, "fee": 0, "currency": "BDT", "paid_at": "2026-11-04 14:13:42", "amount_match": true}
200 OK - not found
{ "success": true, "found": false, "status": "NOT_FOUND", "trx_id": "BK12AB34CD", "message": "No completed payment or received message was found for this transaction ID."}
status
Meaning
COMPLETED
The TrxID belongs to a completed payment of your brand.
RECEIVED_UNCLAIMED
A matching payment SMS arrived, but it is not attached to a payment yet. Submit it with the submit API.
NOT_FOUND
No completed payment and no received SMS for this TrxID.
Direct API

Payment states

The status field of a Direct API payment is always one of these values.

status
Meaning
CREATED
Open and waiting for the customer to pay. You can submit a TrxID.
PROCESSING
A TrxID was verified and the payment is being finalized. Poll the status API.
PENDING
Waiting for manual review. Do not deliver yet.
COMPLETED
Paid and confirmed. Deliver once.
EXPIRED
10 minutes passed without payment. Create a new payment.
FAILED
The payment is closed. Create a new payment.
Direct API

Errors

Every Direct API response has a success field. Errors return "success": false and an error object. Use error.code in your code. The message is for people and may be in Bangla.

422 Unprocessable Entity
{ "success": false, "error": { "code": "transaction_not_found", "message": "We could not find your transaction ID." }}

Authentication and limits

error.code
HTTP
Meaning
invalid_api_key
401
The API key is missing or invalid.
invalid_subdomain
403
The request was sent to the wrong brand subdomain.
rate_limited
429
Too many requests. Slow down.
too_many_attempts
429
Too many wrong TrxID attempts. Try again after 10 minutes.
server_busy
503
The server is busy. Retry in a moment.

Create and lookup

error.code
HTTP
Meaning
invalid_json
400
The body is not valid JSON.
invalid_amount
400
Amount is missing, not a number, 0 or negative, or above 1,000,000.
invalid_success_url
400
success_url is not a valid http(s) URL.
invalid_cancel_url
400
cancel_url is not a valid http(s) URL.
invalid_webhook_url
400
webhook_url is not a valid http(s) URL.
invalid_order_id
400
order_id has a bad format or is longer than 64 characters.
invalid_metadata
400
metadata is not a JSON object.
invalid_idempotency_key
400
idempotency_key has a bad format.
idempotency_conflict
409
The key was already used for a different amount.
create_failed
500
The payment could not be created. Retry with the same key.
missing_identifier
400
Send payment_id, transaction_id or order_id.
payment_not_found
404
No payment matches the identifier.

Submit

error.code
HTTP
Meaning
invalid_method
422
method is missing or not supported by the Direct API.
method_unavailable
422
This method or account type is not available for this payment.
invalid_trx_id
422
trx_id is missing or not 6 to 30 letters or digits.
invalid_sender_number
422
sender_number is not 10 to 15 digits.
transaction_not_found
422
No matching payment SMS yet. Retry after a few seconds.
amount_mismatch
422
The amount in the SMS does not match amount_to_send.
suspicious_message
422
The message looks wrong and was rejected.
transaction_already_used
409
This TrxID was already used for another payment.
payment_already_completed
409
The payment is already completed with a different TrxID.
payment_pending_review
409
The payment is waiting for manual review.
payment_closed
409
The payment is closed. Create a new one.
payment_expired
410
The 10 minutes are over. Create a new payment.
invalid_session
409
The payment session is not valid.
verification_failed
422
The payment could not be verified.
Direct API

Full example

The whole Direct API flow in one script: create, show the details, submit the TrxID, and deliver.

Direct API - create, submit, deliver
<?php$base = 'https://bgpaybd.shop';$key = 'YOUR_API_KEY';function call($url, $key, $body) { $ch = curl_init($url); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_TIMEOUT => 20, CURLOPT_HTTPHEADER => ['API-KEY: ' . $key, 'Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($body), ]); $result = json_decode(curl_exec($ch), true); curl_close($ch); return $result;}// 1. Create the payment$create = call($base . '/api/direct/create', $key, ['amount' => 500, 'order_id' => 'ORD-1001']);if (empty($create['success'])) { exit($create['error']['code'] ?? 'create_failed');}// 2. Show $create['methods'] to your customer (receiver_number, amount_to_send ...)// 3. After the customer pays, submit the wallet TrxID$submit = call($base . '/api/direct/submit', $key, [ 'payment_id' => $create['payment_id'], 'method' => 'bkash', 'trx_id' => $_POST['trx_id'],]);if (($submit['status'] ?? '') === 'COMPLETED' && (float) $submit['amount'] === 500.0) { // 4. Paid. Deliver the order once.} elseif (($submit['error']['code'] ?? '') === 'transaction_not_found') { // The SMS may not have arrived yet. Ask the customer to try again in a few seconds.}
const base = 'https://bgpaybd.shop';const key = 'YOUR_API_KEY';async function call(path, body) { const res = await fetch(base + path, { method: 'POST', headers: { 'API-KEY': key, 'Content-Type': 'application/json' }, body: JSON.stringify(body), }); return res.json();}// 1. Create the paymentconst create = await call('/api/direct/create', { amount: 500, order_id: 'ORD-1001' });if (!create.success) throw new Error(create.error.code);// 2. Show create.methods to your customer (receiver_number, amount_to_send ...)// 3. After the customer pays, submit the wallet TrxIDconst submit = await call('/api/direct/submit', { payment_id: create.payment_id, method: 'bkash', trx_id: req.body.trx_id,});if (submit.status === 'COMPLETED' && Number(submit.amount) === 500) { // 4. Paid. Deliver the order once.} else if (submit.error && submit.error.code === 'transaction_not_found') { // The SMS may not have arrived yet. Ask the customer to try again in a few seconds.}
import requestsBASE = 'https://bgpaybd.shop'HEADERS = {'API-KEY': 'YOUR_API_KEY'}def call(path, body): return requests.post(BASE + path, json=body, headers=HEADERS, timeout=20).json()# 1. Create the paymentcreate = call('/api/direct/create', {'amount': 500, 'order_id': 'ORD-1001'})if not create.get('success'): raise RuntimeError(create['error']['code'])# 2. Show create['methods'] to your customer (receiver_number, amount_to_send ...)# 3. After the customer pays, submit the wallet TrxIDsubmit = call('/api/direct/submit', { 'payment_id': create['payment_id'], 'method': 'bkash', 'trx_id': trx_id,})if submit.get('status') == 'COMPLETED' and float(submit['amount']) == 500.0: pass # 4. Paid. Deliver the order once.elif submit.get('error', {}).get('code') == 'transaction_not_found': pass # The SMS may not have arrived yet. Ask the customer to try again shortly.
Webhooks

Webhook payload

If you send a webhook_url when creating a payment, we notify that URL from our server as soon as the payment is recorded. It works the same for Web Checkout and the Direct API.

This is useful when the customer closes the browser before returning to your site. Webhooks are sent once for each recorded payment and are not retried, so always keep the Verify or Status API as your source of truth.

We send an HTTP POST with application/x-www-form-urlencoded fields. Reply with HTTP 200 within 15 seconds. Redirects are not followed, so the URL must answer directly, and it must be public (no localhost or private IP addresses) with a valid HTTPS certificate.

transactionIdstringrequired
Transaction ID of the payment.
Example: OVKPXW165414
paymentMethodstringrequired
Method used.
Example: bkash
paymentAmountstringrequired
Amount of the order.
Example: 150.000
paymentFeestringrequired
Fee charged, if any.
Example: 0
statusstringrequired
completed or pending.
timestampstringrequired
Unix time when the webhook was signed.
Example: 1760659200
signaturestringrequired
HMAC-SHA256 signature. See the next section.
Example body
transactionId=OVKPXW165414&paymentMethod=bkash&paymentAmount=150.000&paymentFee=0&status=completed&timestamp=1760659200&signature=9f2c...
Webhooks

Verify the signature

The signature proves the webhook came from us. It is an HMAC-SHA256 of the four values below, joined with the | character and used exactly as received, with your Brand API Key as the secret.

Signed string
transactionId|paymentAmount|status|timestamp

Reject the request if the signature does not match or the timestamp is more than 5 minutes old. Ignore webhooks that have no signature or timestamp.

Verify the webhook signature
<?php$secret = 'YOUR_API_KEY'; // your Brand API Key$data = $_POST['transactionId'] . '|' . $_POST['paymentAmount'] . '|' . $_POST['status'] . '|' . $_POST['timestamp'];$expected = hash_hmac('sha256', $data, $secret);if (!hash_equals($expected, $_POST['signature'] ?? '') || abs(time() - (int) $_POST['timestamp']) > 300) { http_response_code(403); exit;}// Signature is valid. Confirm with the Verify or Status API, then mark the order paid once.http_response_code(200);
// routes/web.php (exclude this route from CSRF protection)Route::post('/webhook', function (\Illuminate\Http\Request $request) { $data = implode('|', [ $request->input('transactionId'), $request->input('paymentAmount'), $request->input('status'), $request->input('timestamp'), ]); $expected = hash_hmac('sha256', $data, config('services.pay.key')); if (!hash_equals($expected, (string) $request->input('signature')) || abs(time() - (int) $request->input('timestamp')) > 300) { abort(403); } // Signature is valid. Confirm with the Verify or Status API, then mark the order paid once. return response('OK', 200);});
const crypto = require('crypto');app.use(express.urlencoded({ extended: false }));app.post('/webhook', (req, res) => { const b = req.body; const data = [b.transactionId, b.paymentAmount, b.status, b.timestamp].join('|'); const expected = crypto.createHmac('sha256', 'YOUR_API_KEY').update(data).digest('hex'); const valid = b.signature && b.signature.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(b.signature)) && Math.abs(Date.now() / 1000 - Number(b.timestamp)) <= 300; if (!valid) return res.sendStatus(403); // Signature is valid. Confirm with the Verify or Status API, then mark the order paid once. res.sendStatus(200);});
import hmac, hashlib, timefrom flask import Flask, request, abortapp = Flask(__name__)@app.post('/webhook')def webhook(): f = request.form data = '|'.join([f['transactionId'], f['paymentAmount'], f['status'], f['timestamp']]) expected = hmac.new(b'YOUR_API_KEY', data.encode(), hashlib.sha256).hexdigest() if not hmac.compare_digest(expected, f.get('signature', '')) or abs(time.time() - int(f['timestamp'])) > 300: abort(403) # Signature is valid. Confirm with the Verify or Status API, then mark the order paid once. return 'OK', 200
func webhook(w http.ResponseWriter, r *http.Request) {	r.ParseForm()	data := strings.Join([]string{	r.FormValue("transactionId"), r.FormValue("paymentAmount"),	r.FormValue("status"), r.FormValue("timestamp"),	}, "|")	mac := hmac.New(sha256.New, []byte("YOUR_API_KEY"))	mac.Write([]byte(data))	expected := hex.EncodeToString(mac.Sum(nil))	if !hmac.Equal([]byte(expected), []byte(r.FormValue("signature"))) {	http.Error(w, "forbidden", http.StatusForbidden)	return	}	// Signature is valid. Confirm with the Verify or Status API, then mark the order paid once.	w.WriteHeader(http.StatusOK)}
After the signature is valid, confirm with the Verify or Status API and then mark the order as paid. Mark it paid only once, because the customer redirect, the webhook and a page refresh can all arrive for the same payment.
Go live

Go-live checklist

  1. Keep the key on your server.If your Brand API Key is ever exposed, regenerate it in your dashboard right away.
  2. Always verify.Deliver only when the Verify or Status API says COMPLETED and the amount matches your order.
  3. Handle repeats safely.The customer redirect, the webhook and a page refresh can all arrive for the same payment. Mark an order paid only once.
  4. Use idempotency_key.Use one key per order attempt so a retry after a timeout never creates a second payment.
  5. Plan for the 10 minute window.If the customer comes back after the payment expired, create a new payment instead of reusing the old one.
  6. Check the webhook signature.Verify the HMAC signature and the timestamp before you trust a webhook.
  7. Keep the receiver phone online.Payments are matched from the payment SMS, so the phone must be on, connected to the internet and running the app.
Go live

Receiver app

Install the Payment Receiver App on the phone that receives your mobile wallet payments. It reads the payment confirmation SMS from your wallet provider and sends it to BG PAY BD, so payments can be matched automatically.

  • Connect the app with your account email and the Device Key from your dashboard (Devices).
  • Keep the phone switched on and connected to the internet.
  • Allow the SMS permission.
  • Turn off battery optimization for the app, because payments are confirmed as soon as the SMS reaches us.

Download the app (APK)

Go live

Supported methods

These are the method keys the Direct API accepts. A method appears in the methods list only when you have enabled it for your brand and it can accept the amount.

method
Name
bkash
bKash
nagad
Nagad
rocket
Rocket
upay
Upay
surecash
SureCash
cellfin
Cellfin
tap
tap
ipay
iPay
ok_wallet
OK Wallet
mcash
mCash
easypaisa
Easypaisa
banglaqr
Bangla QR. Show the qr_image_url instead of a receiver number.

Web Checkout supports every method you have enabled on your brand, including bank and international methods.