System Architecture

Overview

SMS Pay is a hosted payment orchestration system. The API server owns payment intent lifecycle, SMS events are evidence, reconciliation decides the outcome, and webhooks notify merchant systems.

Loading diagram...

Components

Component	Responsibility
API Server	Authenticates API keys, creates payment intents, stores SMS events, exposes checkout data, dispatches webhooks.
Checkout UI	Public page that shows payment amount, receiver wallet, reference, expiry, and fallback transaction ID input.
Android SMS Agent	Reads trusted wallet SMS messages on the merchant device and sends them to the backend.
Sandbox Simulator	Sends sandbox SMS events for testing. It never creates payment intents.
Matching engine	Compares SMS amount, receiver, reference, and transaction ID with active payment intents.
Reconciliation dashboard	Lets merchant admins inspect exceptions and manually resolve ambiguous cases.
Webhook dispatcher	Sends signed payment events to verified merchant endpoints.

Step-by-step data flow

Merchant backend creates a payment intent with an API key.
API server stores the intent as PENDING and returns a checkoutUrl.
Customer opens checkout and pays to the displayed receiverMsisdn.
Android SMS Agent or sandbox simulator sends an SMS event.
API server stores the SMS event and queues parsing/matching.
Matching engine confirms, routes to review, or leaves the intent pending.
Dashboard and webhooks reflect the new status.

Code example

Android-style ingestion uses a signed request:

import crypto from "node:crypto";

const body = JSON.stringify({
  sender: "bKash",
  message: "You have received payment Tk 500.00 from 01711111111. Ref ORDER-10045. Fee Tk 0.00. Balance Tk 10000.00. TrxID ABCD1234",
  receiverMsisdn: "01700000001",
  receivedAt: new Date().toISOString(),
  deviceId: "android-device-01"
});

const signature =
  "sha256=" + crypto.createHmac("sha256", process.env.SMS_PAY_LIVE_KEY!).update(body).digest("hex");

Request and response samples

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

{
  "sender": "bKash",
  "message": "You have received payment Tk 500.00 from 01711111111. Ref ORDER-10045. Fee Tk 0.00. Balance Tk 10000.00. TrxID ABCD1234",
  "receiverMsisdn": "01700000001",
  "receivedAt": "2026-05-05T10:00:00.000Z",
  "deviceId": "android-device-01"
}

{
  "id": "sms_123",
  "status": "RECEIVED",
  "queued": true,
  "duplicate": false
}

Edge cases and constraints

Dashboard sandbox endpoints use logged-in dashboard JWT sessions, not API keys.
Merchant API endpoints use API keys and derive environment from the key.
Public checkout returns only checkout-safe fields.
Sandbox SMS events affect only sandbox payment intents.
Live Android SMS events affect only live payment intents.
The simulator is a fake SMS sender, not a checkout or intent creator.

Components

Component	Responsibility
API Server	Authenticates API keys, creates payment intents, stores SMS events, exposes checkout data, dispatches webhooks.
Checkout UI	Public page that shows payment amount, receiver wallet, reference, expiry, and fallback transaction ID input.
Android SMS Agent	Reads trusted wallet SMS messages on the merchant device and sends them to the backend.
Sandbox Simulator	Sends sandbox SMS events for testing. It never creates payment intents.
Matching engine	Compares SMS amount, receiver, reference, and transaction ID with active payment intents.
Reconciliation dashboard	Lets merchant admins inspect exceptions and manually resolve ambiguous cases.
Webhook dispatcher	Sends signed payment events to verified merchant endpoints.

Step-by-step data flow

Merchant backend creates a payment intent with an API key.

API server stores the intent as PENDING and returns a checkoutUrl.

Customer opens checkout and pays to the displayed receiverMsisdn.

Android SMS Agent or sandbox simulator sends an SMS event.

API server stores the SMS event and queues parsing/matching.

Matching engine confirms, routes to review, or leaves the intent pending.

Dashboard and webhooks reflect the new status.

Code example

Android-style ingestion uses a signed request:

import crypto from "node:crypto";

const body = JSON.stringify({
  sender: "bKash",
  message: "You have received payment Tk 500.00 from 01711111111. Ref ORDER-10045. Fee Tk 0.00. Balance Tk 10000.00. TrxID ABCD1234",
  receiverMsisdn: "01700000001",
  receivedAt: new Date().toISOString(),
  deviceId: "android-device-01"
});

const signature =
  "sha256=" + crypto.createHmac("sha256", process.env.SMS_PAY_LIVE_KEY!).update(body).digest("hex");

Request and response samples

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

{
  "sender": "bKash",
  "message": "You have received payment Tk 500.00 from 01711111111. Ref ORDER-10045. Fee Tk 0.00. Balance Tk 10000.00. TrxID ABCD1234",
  "receiverMsisdn": "01700000001",
  "receivedAt": "2026-05-05T10:00:00.000Z",
  "deviceId": "android-device-01"
}

{
  "id": "sms_123",
  "status": "RECEIVED",
  "queued": true,
  "duplicate": false
}

Edge cases and constraints

Dashboard sandbox endpoints use logged-in dashboard JWT sessions, not API keys.

Merchant API endpoints use API keys and derive environment from the key.

Public checkout returns only checkout-safe fields.

Sandbox SMS events affect only sandbox payment intents.

Live Android SMS events affect only live payment intents.

The simulator is a fake SMS sender, not a checkout or intent creator.