BG PAY BD Developer Docs
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.
We host the payment page
Create a payment link, redirect your customer, and we handle method selection and verification. The quickest way to go live.
Start with Web Checkout →Direct APIYou build the payment screen
Get the receiver details through the API, show them on your own page, then submit the customer’s TrxID to confirm the payment.
Start with Direct API →Choose an integration
Use this table to pick the right integration for your product.
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.
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.
API-KEY: YOUR_API_KEYContent-Type: application/jsonRequests 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.
- 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
Rate limits
Direct API calls are limited per brand, per minute. Going over the limit returns HTTP 429 with the error code rate_limited.
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.
- Your serverCalls
POST /api/payment/createwith the amount and your return URLs. - BG PAY BDReplies with a
payment_url. - Your serverRedirects the customer to that
payment_url. - CustomerChooses a method, pays, and enters the transaction ID.
- BG PAY BDVerifies the payment, sends the webhook (if set) and redirects the customer to your
success_url. - Your serverCalls
POST /api/payment/verifyand delivers the order when the status isCOMPLETED.
Create a payment
Creates a payment link for one order. Redirect your customer to the returned payment_url.
Body parameters
150 or 150.50Default Namedefault@gmail.com{"order_id": "1001"}_ 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
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); // Expressimport 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 hereimport 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
{ "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.
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.
OVKPXW165414bkash150.0000completed, pending (waiting for confirmation or manual review) or failed (cancelled, expired or closed).https://yourdomain.com/success?transactionId=OVKPXW165414&paymentMethod=bkash&paymentAmount=150.000&paymentFee=0&status=completedVerify 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.
transactionId from your success URL or webhook.OVKPXW165414Request
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 codeimport 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
{ "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
amount matches your order.If the ID is unknown for your account, the response is "status": 0 with a message.
Errors
Failed requests return JSON with "status": 0 and a message.
{ "status": 0, "message": "Your request is invalid."}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.API-KEY header is missing, wrong, or belongs to a deleted brand.idempotency_key was already used with a different amount.idempotency_key."status": "error" when metadata is not a JSON object.metadata as a JSON object.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.
- Your serverCalls
POST /api/direct/createwith the amount. You get apayment_idand amethodslist. - Your serverShows the receiver number (or QR code) and
amount_to_sendon your own page. - CustomerSends the money from their wallet and gets a wallet TrxID.
- Your serverCalls
POST /api/direct/submitwith thattrx_id. - BG PAY BDMatches the TrxID with the received payment SMS and completes the payment.
- Your serverDelivers when the status is
COMPLETEDand the amount matches your order.
transaction_not_found. Retry after a few seconds. See Receiver app.amount_to_send from the method they chose. It already includes any fee.Create a payment
Creates a payment and returns the methods your customer can pay with. A payment stays open for 10 minutes.
Body parameters
_ - . :, up to 64 characters. You can look the payment up by it later.Default Namedefault@gmail.com+ only, up to 20 characters.success_url and cancel_url, the response also contains a payment_url.success_url._ or -. The same key returns the same open payment. A different amount with the same key returns HTTP 409.Request
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 customeruse 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 customerconst 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 customerimport 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 customerimport 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
{ "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
bkash. Use it as method when you submit.personal, agent or payment. Use it as account_type when you submit.banglaqr.0 means no limit.["trx_id"].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.
Get methods
Returns the same payment object as create, with a fresh methods list. Use it if the customer reopens your payment screen.
payment_id from create. You can also send transaction_id or order_id.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.
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.
Body parameters
transaction_id or order_id.bkash. Must be one of the methods from create.personal, agent or payment. If you leave it out, the first available type for the method is used.Request
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
{ "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.
{ "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.
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).Payment status
Returns the current state of a payment. Use it to poll after a 202, and as your source of truth before delivering.
payment_id, transaction_id or order_id. When you use order_id, the latest payment with that reference is returned.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(){ "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.
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.
amount_match.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(){ "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}{ "success": true, "found": false, "status": "NOT_FOUND", "trx_id": "BK12AB34CD", "message": "No completed payment or received message was found for this transaction ID."}Payment states
The status field of a Direct API payment is always one of these values.
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.
{ "success": false, "error": { "code": "transaction_not_found", "message": "We could not find your transaction ID." }}Authentication and limits
Create and lookup
success_url is not a valid http(s) URL.cancel_url is not a valid http(s) URL.webhook_url is not a valid http(s) URL.order_id has a bad format or is longer than 64 characters.metadata is not a JSON object.idempotency_key has a bad format.payment_id, transaction_id or order_id.Submit
method is missing or not supported by the Direct API.trx_id is missing or not 6 to 30 letters or digits.sender_number is not 10 to 15 digits.amount_to_send.Full example
The whole Direct API flow in one script: create, show the details, submit the TrxID, and 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.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.
OVKPXW165414bkash150.0000completed or pending.1760659200transactionId=OVKPXW165414&paymentMethod=bkash&paymentAmount=150.000&paymentFee=0&status=completed×tamp=1760659200&signature=9f2c...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.
transactionId|paymentAmount|status|timestampReject 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.
<?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', 200func 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)}Go-live checklist
- Keep the key on your server.If your Brand API Key is ever exposed, regenerate it in your dashboard right away.
- Always verify.Deliver only when the Verify or Status API says
COMPLETEDand the amount matches your order. - 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.
- Use idempotency_key.Use one key per order attempt so a retry after a timeout never creates a second payment.
- 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.
- Check the webhook signature.Verify the HMAC signature and the timestamp before you trust a webhook.
- 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.
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.
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.
qr_image_url instead of a receiver number.Web Checkout supports every method you have enabled on your brand, including bank and international methods.