Sandbox Testing

Overview

Sandbox lets you test the full payment lifecycle without moving real money. Sandbox payment intents, SMS events, devices, simulator runs, and webhooks are isolated from live data.

Critical rule:

The SMS Simulator only sends SMS events. It never creates payment intents.

Correct sandbox flow:

Create a sandbox payment intent.
Open the checkout URL.
Use the Visual SMS Simulator or raw simulator endpoint to send a matching SMS event.
Verify the intent becomes PAID.
Verify webhook delivery and dashboard records.

Loading diagram...

Step-by-step guide

1. Create a sandbox intent

POST /v1/payments/intents
X-Api-Key: sk_test_xxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "amount": 500,
  "currency": "BDT",
  "customerReference": "ORDER-SBX-1001",
  "receiverMsisdn": "01700000001",
  "idempotencyKey": "sandbox_ORDER-SBX-1001",
  "ttlSeconds": 300
}

2. Open checkout

Use the returned checkoutUrl. Confirm it displays:

amount: BDT 500
receiver wallet: 01700000001
reference: ORDER-SBX-1001
expiry countdown
fallback transaction ID input

3. Send a sandbox SMS event

Use Dashboard -> Sandbox -> Visual SMS Simulator for a form-based test, or use the raw API endpoint for automation.

4. Verify results

Check:

payment intent status
linked SMS event
match status and reason
webhook delivery status

Visual SMS Simulator

The visual simulator is a fake Android SMS sender for sandbox. It generates bKash-style SMS text from form fields and sends it to the server as a sandbox SMS event.

It does not:

create payment intents
update live data
expose API keys in the browser
bypass reconciliation

Supported form fields:

Field	Description
`paymentMethod`	`BKASH_PAYMENT` or `BKASH_SEND_MONEY`.
`amount`	Amount in the provider SMS.
`customerReference`	Reference text included in the generated SMS.
`receiverMsisdn`	Merchant wallet number shown on checkout.
`senderMsisdn`	Payer wallet number.
`trxId`	Provider transaction ID.
`fee`	Optional provider fee.
`balance`	Optional wallet balance.
`receivedAt`	Optional received timestamp.

Raw simulator API

POST /v1/sandbox/sms-events/simulate
X-Api-Key: sk_test_xxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "message": "You have received payment Tk 500.00 from 01711111111. Ref ORDER-SBX-1001. Fee Tk 0.00. Balance Tk 10000.00. TrxID TEST1234 at 05/05/2026 10:00",
  "receiverMsisdn": "01700000001",
  "receivedAt": "2026-05-05T10:00:00.000Z"
}

{
  "id": "sms_123",
  "status": "MATCHED",
  "matchStatus": "MATCHED",
  "paymentIntentId": "b5012f33-207e-4999-bf8d-5a1ebb10988e",
  "parsedTxnId": "TEST1234",
  "parsedAmount": "500"
}

Guided dashboard cases

Case	Expected result
Successful payment	Matching amount, receiver, and reference marks the intent `PAID`.
Review required	Ambiguous or partial match routes to `REVIEW_REQUIRED`.
Wrong amount	Intent remains `PENDING` or moves to review depending on other signals.
Duplicate SMS	Duplicate transaction ID is rejected as duplicate.
Expired payment	Expired intent becomes `EXPIRED` and cannot auto-confirm.
Webhook delivery	Successful payment queues `payment.paid`; dashboard shows delivery status.

Code example

async function simulateSandboxSms() {
  const response = await fetch("https://api.smspaybd.com/v1/sandbox/sms-events/simulate", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": process.env.SMS_PAY_SANDBOX_KEY!,
    },
    body: JSON.stringify({
      message:
        "You have received payment Tk 500.00 from 01711111111. Ref ORDER-SBX-1001. Fee Tk 0.00. Balance Tk 10000.00. TrxID TEST1234",
      receiverMsisdn: "01700000001",
      receivedAt: new Date().toISOString()
    }),
  });

  return response.json();
}

Edge cases and constraints

Live API keys cannot call /v1/sandbox/sms-events/simulate.
Sandbox simulator events match only sandbox payment intents.
The simulator does not create intents; create the intent first.
The payment intent must still be active.
Amount and receiver must match exactly.
One transaction ID cannot be reused.
Public checkout never exposes simulator controls.