How It Works

Overview

The payment flow is intent-first. A payment intent is created before the customer pays. The SMS event is only the confirmation signal. This separation keeps checkout, SMS ingestion, reconciliation, and fulfillment predictable.

Loading diagram...

Step-by-step guide

1. Create the payment intent

Your backend creates a payment intent with amount, BDT currency, customer reference, idempotency key, optional customer fields, and optional receiving wallet override.

POST /v1/payments/intents
X-Api-Key: sk_test_xxxxxxxxxxxxxxxxx

The server sets:

• status: PENDING
• expiresAt, default 5 minutes from creation
• receiverMsisdn, the merchant wallet number
• checkoutUrl, the hosted payment page

2. Show hosted checkout

The checkout page displays:

• exact amount
• merchant receiving wallet number
• unique reference number
• expiry countdown
• fallback transaction ID input

The public checkout endpoint is read-only:

GET /v1/checkout/:id

3. Customer pays

The customer sends the exact amount to the displayed merchant wallet number and includes the displayed reference when the wallet app supports a reference field.

4. Android SMS Agent sends the SMS event

In live mode, the Android SMS Agent forwards the provider SMS to:

POST /v1/sms-events/incoming
X-Api-Key: sk_live_xxxxxxxxxxxxxxxxx
X-Signature: sha256=<hmac>

In sandbox, the Visual SMS Simulator or raw simulator endpoint sends an equivalent sandbox SMS event.

5. Gateway reconciles

Primary instant match requires:

• exact amount
• receiver wallet matches the intent receiver
• SMS reference matches the payment intent reference
• intent is still active
• SMS transaction ID is not already used

If these checks pass, the intent becomes PAID and a payment.paid webhook is queued.

6. Manual fallback with transaction ID

If the customer enters a transaction ID on checkout, the server compares it against stored SMS events. The fallback confirms only when:

• transaction ID matches a stored SMS event
• amount matches exactly
• receiver wallet matches
• intent has not expired
• SMS event is not already linked to another payment

Code example

async function createCheckout(order: { id: string; total: number }) {
  const response = await fetch("https://api.smspaybd.com/v1/payments/intents", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": process.env.SMS_PAY_SANDBOX_KEY!,
    },
    body: JSON.stringify({
      amount: order.total,
      currency: "BDT",
      customerReference: order.id,
      idempotencyKey: `order_${order.id}`,
      ttlSeconds: 300
    }),
  });

  if (!response.ok) throw new Error("Could not create payment intent");
  return response.json();
}

Request and response samples

Checkout details:

GET /v1/checkout/b5012f33-207e-4999-bf8d-5a1ebb10988e

{
  "id": "b5012f33-207e-4999-bf8d-5a1ebb10988e",
  "amount": "500",
  "currency": "BDT",
  "status": "PENDING",
  "environment": "SANDBOX",
  "customerReference": "ORDER-10045",
  "receiverMsisdn": "01700000001",
  "expiresAt": "2026-05-05T10:05:00.000Z"
}

Fallback confirmation:

POST /v1/checkout/b5012f33-207e-4999-bf8d-5a1ebb10988e/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"
}

Edge cases and constraints

• Late SMS events cannot auto-confirm expired intents.
• Wrong amount or wrong receiver does not mark the intent paid.
• Partial matches can become REVIEW_REQUIRED.
• Duplicate transaction IDs are rejected.
• Checkout refreshes status silently; do not build fulfillment from browser polling alone.