Reconciliation

Overview

Reconciliation turns SMS evidence into payment status. The gateway stores every trusted SMS event, parses known provider formats, and matches it to the correct payment intent using deterministic key-based matching only.

There are exactly two valid matching paths:

1. Reference match — automatic confirmation
2. Transaction ID fallback — customer-submitted confirmation

Weak signals such as amount alone, receiver alone, sender alone, or time proximity never produce a match or trigger review.

How matching works

Path 1 — Reference match (automatic)

When an SMS is ingested and parsed, the gateway checks whether the parsedReference in the SMS equals the customerReference of a pending, non-expired payment intent.

The lookup must satisfy all four conditions:

Then:

If no intent has a matching reference, the SMS stays PENDING/unmatched. It is not automatically attached to any other intent.

The same logic runs in reverse when a new intent is created: the gateway checks whether an already-ingested SMS is waiting with a matching reference.

Path 2 — Transaction ID fallback (customer confirmation)

If the customer paid but the reference was missing or incorrect, they can enter the bKash Transaction ID on the checkout page.

The lookup must satisfy all four conditions:

Then:

What is never allowed

• Matching by amount alone
• Matching by receiver alone
• Matching by sender alone
• Matching by time proximity alone
• Auto-attaching pending SMS events to newly created intents unless the reference matches
• Moving a new intent to REVIEW_REQUIRED because an old unmatched SMS has the same amount

Checkout page flow

1. Customer selects a payment method before checkout creates the payment intent.
2. Checkout only shows methods that are enabled for the merchant, enabled for the current environment, and backed by at least one active receiver account.
3. Customer sees the method-specific receiver snapshot and their reference code.
4. Customer pays with the selected method and enters the reference code in the provider app.
5. Page polls every 5 seconds for automatic confirmation.
6. After 15 seconds, if still pending, a Transaction ID input appears.
7. Customer can enter the bKash TrxID from their SMS confirmation.
8. If TrxID + receiver + paymentMethod match and amount is exact → paid instantly.
9. If amount differs → review required.
10. If trxId confirmation fails, checkout shows a user-friendly message. Raw backend reason codes are never shown.

Hosted checkout method selection

• Receiver account selection happens when the intent is created, using merchant + environment + payment method.
• Checkout never creates the intent before the payment method is selected.
• If no active receiver account exists for an enabled method, that method is not shown to the customer.

Code example

Your system should treat webhooks as the source of fulfillment:

async function handlePaymentPaid(payload: {
  data: { payment_intent_id: string; customer_reference: string };
}) {
  const order = await db.orders.findUnique({
    where: { reference: payload.data.customer_reference },
  });

  if (!order || order.status === "paid") return;

  await db.orders.update({
    where: { id: order.id },
    data: {
      status: "paid",
      gatewayPaymentIntentId: payload.data.payment_intent_id,
    },
  });
}

Do not fulfil orders from the checkout redirect URL. The redirect is a UX hint only. Always verify payment status via the webhook or a server-side GET on the payment intent.

Request and response samples

Retrieve a payment intent after matching:

GET /v1/payments/intents/b5012f33-207e-4999-bf8d-5a1ebb10988e
X-Api-Key: sk_test_xxxxxxxxxxxxxxxxx

{
  "id": "b5012f33-207e-4999-bf8d-5a1ebb10988e",
  "environment": "SANDBOX",
  "amount": "500",
  "currency": "BDT",
  "status": "PAID",
  "customerReference": "ORDER-10045",
  "receiverMsisdn": "01700000001",
  "checkoutUrl": "https://smspaybd.com/checkout/b5012f33-207e-4999-bf8d-5a1ebb10988e",
  "expiresAt": "2026-05-05T10:05:00.000Z"
}

Review-required webhook:

{
  "event": "payment.review_required",
  "environment": "SANDBOX",
  "timestamp": "2026-05-05T10:01:00.000Z",
  "data": {
    "payment_intent_id": "b5012f33-207e-4999-bf8d-5a1ebb10988e",
    "amount": "500",
    "currency": "BDT",
    "customer_reference": "ORDER-10045"
  }
}

Dashboard review actions

Merchant admins can:

• inspect parsed SMS fields
• view the linked payment intent
• approve a match (for REVIEW_REQUIRED intents)
• reject an SMS event
• retry processing after parser or configuration fixes
• add notes for audit history

Edge cases and constraints

• Wrong amount with matching reference → REVIEW_REQUIRED, not PAID.
• Wrong amount with matching trxId → REVIEW_REQUIRED, not PAID.
• Missing or wrong reference → SMS stays PENDING; customer must use trxId fallback.
• Duplicate trxId → second SMS is rejected as FAILED with reason duplicate_trx_id.
• Expired intents cannot be auto-confirmed or manually confirmed via trxId.
• Sandbox and live matching never cross environments.
• One SMS event can only be linked to one payment intent.
• One payment intent can only be paid once.

Primary instant match requires:

• exact amount match
• receiver wallet match
• reference match
• active, unexpired payment intent
• unused SMS transaction ID

Fallback manual confirmation uses transaction ID plus amount and receiver validation.

Step-by-step guide

1. Create a payment intent before payment collection.
2. Receive a provider SMS through Android Agent or sandbox simulator.
3. Gateway parses amount, transaction ID, reference, sender, receiver, and timestamp.
4. Gateway compares the SMS event with active intents in the same merchant and environment.
5. If exact checks pass, status becomes PAID.
6. If signals partially match, status becomes REVIEW_REQUIRED.
7. If no useful match exists, the SMS remains pending for review or later matching.
8. Merchant admins inspect unresolved items in the dashboard.

Matching rules

Primary instant match

The server marks the payment intent PAID when:

Fallback manual match

When a customer enters trxId on checkout, the server validates:

• transaction ID matches a stored SMS event
• amount matches exactly
• receiver wallet matches
• intent is active
• SMS event is unused

If valid, the payment becomes PAID.

Code example

Your system should treat webhooks as the source of fulfillment:

async function handlePaymentPaid(payload: {
  data: { payment_intent_id: string; customer_reference: string };
}) {
  const order = await db.orders.findUnique({
    where: { reference: payload.data.customer_reference },
  });

  if (!order || order.status === "paid") return;

  await db.orders.update({
    where: { id: order.id },
    data: {
      status: "paid",
      gatewayPaymentIntentId: payload.data.payment_intent_id,
    },
  });
}

Request and response samples

Retrieve a payment intent after matching:

GET /v1/payments/intents/b5012f33-207e-4999-bf8d-5a1ebb10988e
X-Api-Key: sk_test_xxxxxxxxxxxxxxxxx

{
  "id": "b5012f33-207e-4999-bf8d-5a1ebb10988e",
  "environment": "SANDBOX",
  "amount": "500",
  "currency": "BDT",
  "status": "PAID",
  "customerReference": "ORDER-10045",
  "receiverMsisdn": "01700000001",
  "checkoutUrl": "https://smspaybd.com/checkout/b5012f33-207e-4999-bf8d-5a1ebb10988e",
  "expiresAt": "2026-05-05T10:05:00.000Z"
}

Review-required webhook:

{
  "event": "payment.review_required",
  "environment": "SANDBOX",
  "timestamp": "2026-05-05T10:01:00.000Z",
  "data": {
    "payment_intent_id": "b5012f33-207e-4999-bf8d-5a1ebb10988e",
    "amount": "500",
    "currency": "BDT",
    "customer_reference": "ORDER-10045"
  }
}

Dashboard review actions

Merchant admins can:

• inspect parsed SMS fields
• view ranked candidate payment intents
• approve a match
• reject an SMS event
• retry processing after parser or configuration fixes
• add notes for audit history

Edge cases and constraints

• Wrong amount does not mark paid.
• Wrong receiver does not mark paid.
• Missing reference can route to review or stay pending.
• Duplicate transaction ID becomes duplicate/failed and cannot confirm another intent.
• Expired intents cannot be auto-confirmed.
• Sandbox and live matching never cross environments.
• Manual approval should be used only when the SMS event clearly represents the customer payment.