Pay-In · Bangladesh
Overview
Pay-in API for collecting payments from customers in Bangladesh (country code bd). Two order modes are supported:
| Mode | Path | Description |
|---|---|---|
| Cashier | /pay/prePay | Default. Returns cashierUrl; the customer pays on the platform H5 cashier |
| API | /pay/transOrder | method is required. Returns payData / payDataType (upstream payment page URL) |
- Amounts are in BDT. Pay-in does not accept a non-zero fraction: use a positive integer Taka (e.g.
100,100.0,100.00are accepted;100.50is rejected). - See Regional Payment Guide — Bangladesh for
methodcodes and extra fields. Supported values:BKASH,BKASH_P(personal),BKASH_A(corporate),NAGAD,NAGAD_P(personal),NAGAD_A(corporate).
Integration note
Cashier mode is enabled by default. Contact support to whitelist the merchant before integrating API mode.
Request Headers
Shared by both modes:
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | Fixed: application/json |
Cashier Mode (prePay)
Create a pre-order, receive cashierUrl, and send the customer to the platform cashier to choose a method and pay.
Endpoint
Domain: Prefer unified host
openapi.toppayment.com(path unchanged); legacy country domain (e.g.global-bd-openapi.toppayment.com) remains available.
| Environment | URL |
|---|---|
| Sandbox | https://openapi.toppayment.com/sandbox/bd/pay/prePay |
| Production | https://openapi.toppayment.com/bd/pay/prePay |
Request Body
| Field | Required | Type | Description |
|---|---|---|---|
| mchNo | M | String(32) | Merchant number |
| orderNum | M | String(64) | Merchant order number |
| amount | M | Number | Amount in BDT as a positive integer Taka (100.00 is treated as an integer; 100.50 is rejected) |
| productDetail | M | String(100) | Product description |
| method | O | String(16) | Optional; if omitted, the customer chooses at the cashier. Supports BKASH, BKASH_P (personal), BKASH_A (corporate), NAGAD, NAGAD_P (personal), NAGAD_A (corporate). See Bangladesh guide |
| timestamp | M | String(13) | Millisecond timestamp |
| customerName | M | String(64) | Customer name |
| customerEmail | M | String(64) | Customer email |
| customerPhone | O | String(32) | Customer wallet number — recommended format: starts with 01, 11 digits total |
| downNotifyUrl | M | String(255) | Webhook URL |
| redirectUrl | O | String(512) | Redirect URL after payment |
| sign | M | String | RSA signature — see Signature |
Request Examples
{
"mchNo": "{{mchNo}}",
"orderNum": "BD1234561",
"amount": 1000.00,
"productDetail": "test",
"method": "BKASH",
"timestamp": "1749451858772",
"customerName": "Rahim Uddin",
"customerEmail": "[email protected]",
"customerPhone": "01880612345",
"downNotifyUrl": "https://example.com/notify",
"redirectUrl": "https://example.com/paid",
"sign": "Generate per signature rules and replace"
}
{
"mchNo": "{{mchNo}}",
"orderNum": "BD1234562",
"amount": 500,
"productDetail": "test",
"method": "NAGAD",
"timestamp": "1749451858772",
"customerName": "Rahim Uddin",
"customerEmail": "[email protected]",
"customerPhone": "01880612345",
"downNotifyUrl": "https://example.com/notify",
"redirectUrl": "https://example.com/paid",
"sign": "Generate per signature rules and replace"
}
For a personal or corporate account, replace method in the examples above with BKASH_P / BKASH_A or NAGAD_P / NAGAD_A. The other fields stay the same.
HTTP Response
Shared by both modes:
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | HTTP response content type specification Fixed value: application/json |
Response Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| success | M | Boolean | Whether the request succeeded |
| code | M | String | 9999: success; otherwise failure |
| msg | O | String | Message; null on success |
| timeStamp | M | Number | Response timestamp (ms) |
| data | M | Object | Payload |
| orderNum | M | String | Merchant order number |
| platOrderNum | M | String | Platform order number |
| amount | M | Number | Amount |
| fee | M | Number | Fee |
| method | O | String | Payment method (may be empty if not sent in the request) |
| productDetail | M | String | Product description |
| customerName | M | String | Customer name |
| customerEmail | M | String | Customer email |
| customerPhone | O | String | Customer wallet number |
| validTime | M | Number | Expiry timestamp (ms) |
| cashierUrl | M | String | Platform cashier URL |
Response note
Cashier mode does not return payData / payDataType. Those fields appear only in API mode.
Response Example
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "BD1234561",
"platOrderNum": "BDPTJ2009093829059153920",
"amount": 1000.00,
"fee": 20.00,
"method": "BKASH",
"productDetail": "test",
"customerName": "Rahim Uddin",
"customerEmail": "[email protected]",
"customerPhone": "01880612345",
"validTime": 1767926672819,
"cashierUrl": "https://example.cashier/pay"
}
}
API Mode (transOrder)
Specify the payment method in the request, place the order directly with the channel, and receive payData / payDataType without the platform H5 cashier.
Endpoint
| Environment | URL |
|---|---|
| Sandbox | https://openapi.toppayment.com/sandbox/bd/pay/transOrder |
| Production | https://openapi.toppayment.com/bd/pay/transOrder |
Request Body
Differences from cashier mode:
| Field | Required | Type | Description |
|---|---|---|---|
| method | M | String(16) | Payment method (Bangladesh) Required in API mode. Supports BKASH, BKASH_P (personal), BKASH_A (corporate), NAGAD, NAGAD_P (personal), NAGAD_A (corporate) — see Bangladesh guide |
All other fields match cashier mode.
Request Examples
{
"mchNo": "{{mchNo}}",
"orderNum": "BDPAYINAPI1234561",
"amount": 1000.00,
"productDetail": "test",
"method": "BKASH",
"timestamp": "1749451858772",
"customerName": "Rahim Uddin",
"customerEmail": "[email protected]",
"customerPhone": "01880612345",
"downNotifyUrl": "https://example.com/notify",
"redirectUrl": "https://example.com/paid",
"sign": "Generate per signature rules and replace"
}
{
"mchNo": "{{mchNo}}",
"orderNum": "BDPAYINAPI1234562",
"amount": 500,
"productDetail": "test",
"method": "NAGAD",
"timestamp": "1749451858772",
"customerName": "Rahim Uddin",
"customerEmail": "[email protected]",
"customerPhone": "01880612345",
"downNotifyUrl": "https://example.com/notify",
"redirectUrl": "https://example.com/paid",
"sign": "Generate per signature rules and replace"
}
For a personal or corporate account, replace method in the examples above with BKASH_P / BKASH_A or NAGAD_P / NAGAD_A. The other fields stay the same.
Response Body Parameters
Common fields (success, code, msg, timeStamp, and data.orderNum, platOrderNum, amount, fee, method, productDetail, customerName, customerEmail, customerPhone, validTime) match cashier mode. API mode focuses on:
| Field | Required | Type | Description |
|---|---|---|---|
| payData | M | String | Payment payload — usually an upstream payment page URL; meaning depends on payDataType |
| payDataType | M | String | Payment data type; Bangladesh wallet flows use CASHIER_URL |
| cashierUrl | O | String | May also be returned; in API mode prefer payData |
payDataType Reference
| payDataType | Description | Typical methods |
|---|---|---|
CASHIER_URL | Upstream payment page URL | BKASH, BKASH_P, BKASH_A, NAGAD, NAGAD_P, NAGAD_A |
Response Example
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "BDPAYINAPI1234561",
"platOrderNum": "BDPTJ2009093829059153920",
"amount": 1000.00,
"fee": 20.00,
"method": "BKASH",
"productDetail": "test",
"customerName": "Rahim Uddin",
"customerEmail": "[email protected]",
"customerPhone": "01880612345",
"validTime": 1767926672819,
"cashierUrl": "https://sg-cb.megipay.com/api/v1/sandbox/order.html?type=1&order_no=MegExample",
"payData": "https://sg-cb.megipay.com/api/v1/sandbox/order.html?type=1&order_no=MegExample",
"payDataType": "CASHIER_URL"
}
}
Notification
Both modes share the same callback. Bangladesh callbacks are fixed to v1.
HTTP Request
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | Fixed value: application/json |
Notification Body
| Field | Required | Type | Description |
|---|---|---|---|
| platOrderNum | M | String | Platform order number |
| version | M | String | Version, fixed to v1 |
| orderNum | M | String | Merchant order number, same as orderNum at order placement |
| amount | M | Number | Amount in BDT |
| fee | M | Number | Fee |
| customerName | M | String | Customer name |
| customerEmail | M | String | Customer email |
| customerPhone | O | String | Customer wallet number |
| status | M | String | Transaction status See Transaction Status Codes |
| sign | M | String | Callback signature — see Signature |
Response
Verify the signature, then return the plain string SUCCESS only.
SUCCESS
Notification Example
{
"platOrderNum": "PRE2009165141186183168",
"version": "v1",
"orderNum": "BD1234561",
"amount": 1000,
"fee": 20,
"customerName": "Rahim Uddin",
"customerEmail": "[email protected]",
"customerPhone": "01880612345",
"status": "SUCCESS",
"sign": "Verify per signature rules"
}
