Search pages in the SMS Pay documentation.
https://api.smspaybd.com/v1
Use sandbox keys while integrating and live keys only after launch readiness is complete.
Merchant backend API calls use X-Api-Key.
X-Api-Key: sk_test_xxxxxxxxxxxxxxxxx
Never expose API keys in browser JavaScript.
| Surface | Authentication |
|---|---|
| Payment intents | X-Api-Key |
| Webhook endpoints and deliveries | X-Api-Key |
| Public checkout | No API key |
| Dashboard sandbox tools | Dashboard login session |
| Android SMS forwarding | Handled by the SMS Pay Android app |
POST /v1/payments/intents
X-Api-Key: sk_test_xxxxxxxxxxxxxxxxx
Content-Type: application/json
{
"amount": 500,
"currency": "BDT",
"merchantReference": "ORDER-10045",
"paymentMethod": "bkash_send_money",
"language": "bn",
"idempotencyKey": "payment_intent_ORDER-10045",
"ttlSeconds": 300,
"successUrl": "https://merchant.example.com/payments/success",
"failedUrl": "https://merchant.example.com/payments/failed",
"cancelUrl": "https://merchant.example.com/cart",
"expiredUrl": "https://merchant.example.com/payments/expired"
}
{
"id": "b5012f33-207e-4999-bf8d-5a1ebb10988e",
"environment": "SANDBOX",
"amount": "500",
"currency": "BDT",
"status": "PENDING",
"customerReference": "SP7A91BC2D0",
"merchantReference": "ORDER-10045",
"paymentMethod": "BKASH_SEND_MONEY",
"receiverMsisdn": "01700000001",
"checkoutUrl": "https://smspaybd.com/checkout/b5012f33-207e-4999-bf8d-5a1ebb10988e?language=bn",
"expiresAt": "2026-05-05T10:05:00.000Z"
}
| Field | Required | Notes |
|---|---|---|
amount | Yes | Payment amount in BDT. Supports up to two decimals. |
currency | No | Must be BDT; defaults to BDT. |
merchantReference | No | Your order or invoice ID. Use this for long merchant references. |
customerReference | No | Short provider-facing reference, 16 characters or fewer. Omit to let SMS Pay generate it. |
idempotencyKey | Yes | Stable retry key for this order/payment creation request. |
paymentMethod | No | Optional selected method. Accepts canonical values like BKASH_SEND_MONEY or lowercase aliases like bkash_send_money. Omit to let hosted checkout handle method selection. |
language | No | Hosted checkout language: en or bn. Defaults to en; included in checkoutUrl only when provided. |
customerId | No | Optional stored customer/payer ID. |
expectedSenderMsisdn | No | Optional payer phone number for visibility/scoring. |
expectedTrxId | No | Optional provider transaction ID if collected before intent creation. |
ttlSeconds | No | Intent lifetime. Defaults to 300 seconds. |
successUrl | No | Browser redirect after paid status. Not fulfillment proof. |
failedUrl | No | Browser redirect after failure or rejection. |
cancelUrl | No | Browser redirect when customer cancels. |
expiredUrl | No | Browser redirect after expiry. |
Supported canonical paymentMethod response values are BKASH_PAYMENT, BKASH_SEND_MONEY, BKASH_CASHOUT, NAGAD_PAYMENT, NAGAD_SEND_MONEY, and NAGAD_CASHOUT. A selected method must be enabled for the merchant and have an active receiver account.
When paymentMethod is omitted, hosted checkout shows enabled options if more than one method is available. If exactly one method is available, hosted checkout selects it automatically. If language is omitted or absent from the checkout URL, hosted checkout starts in English.
GET /v1/payments/intents?status=PENDING&page=1&limit=20
X-Api-Key: sk_test_xxxxxxxxxxxxxxxxx
{
"data": [],
"total": 0,
"page": 1,
"limit": 20
}
GET /v1/payments/intents/:id
X-Api-Key: sk_test_xxxxxxxxxxxxxxxxx
{
"id": "b5012f33-207e-4999-bf8d-5a1ebb10988e",
"status": "PAID",
"amount": "500",
"currency": "BDT",
"customerReference": "SP7A91BC2D0",
"merchantReference": "ORDER-10045",
"paymentMethod": "BKASH_PAYMENT",
"receiverMsisdn": "01700000001"
}
GET /v1/checkout/:id
{
"id": "b5012f33-207e-4999-bf8d-5a1ebb10988e",
"amount": "500",
"currency": "BDT",
"status": "PENDING",
"environment": "SANDBOX",
"customerReference": "SP7A91BC2D0",
"paymentMethod": "BKASH_PAYMENT",
"receiverMsisdn": "01700000001",
"expiresAt": "2026-05-05T10:05:00.000Z"
}
Public checkout status is for display only. Your backend should verify status before fulfillment.
POST /v1/checkout/:id/confirm
Content-Type: application/json
{
"trxId": "ABCD1234"
}
{
"matched": true,
"paymentIntentId": "b5012f33-207e-4999-bf8d-5a1ebb10988e",
"smsEventId": "c90a5751-a3ca-483e-871b-e3a094ea7523",
"reason": "manual_trx_id_confirmed"
}
POST /v1/webhooks/endpoints
X-Api-Key: sk_test_xxxxxxxxxxxxxxxxx
Content-Type: application/json
{
"url": "https://merchant.example.com/webhooks/sms-pay",
"secret": "whsec_minimum_16_characters",
"eventTypes": [
"payment.paid",
"payment.review_required",
"payment.expired",
"payment.rejected"
]
}
{
"id": "wh_123",
"url": "https://merchant.example.com/webhooks/sms-pay",
"eventTypes": [
"payment.paid",
"payment.review_required",
"payment.expired",
"payment.rejected"
],
"environment": "SANDBOX",
"isVerified": false,
"isActive": true,
"createdAt": "2026-05-05T10:00:00.000Z"
}
Verify endpoint:
POST /v1/webhooks/endpoints/:id/verify
X-Api-Key: sk_test_xxxxxxxxxxxxxxxxx
List deliveries:
GET /v1/webhooks/deliveries
X-Api-Key: sk_test_xxxxxxxxxxxxxxxxx
{
"data": [
{
"id": "delivery_123",
"endpointId": "wh_123",
"paymentIntentId": "b5012f33-207e-4999-bf8d-5a1ebb10988e",
"eventType": "payment.paid",
"status": "DELIVERED",
"attempt": 1,
"statusCode": 200,
"idempotencyKey": "payment.paid:b5012f33-207e-4999-bf8d-5a1ebb10988e",
"deliveredAt": "2026-05-05T10:01:00.000Z",
"createdAt": "2026-05-05T10:01:00.000Z"
}
],
"total": 1
}
{
"event": "payment.paid",
"environment": "SANDBOX",
"timestamp": "2026-05-05T10:01:00.000Z",
"data": {
"payment_intent_id": "b5012f33-207e-4999-bf8d-5a1ebb10988e",
"amount": "500",
"currency": "BDT",
"customer_reference": "SP7A91BC2D0",
"merchant_reference": "ORDER-10045"
}
}
customerReference is provider-facing and must be unique per merchant environment and 16 characters or fewer.merchantReference should hold your long order or invoice reference.idempotencyKey should be stable per order create request.