FAQ

Overview

This page answers the questions developers and operators most often hit while integrating SMS Pay.

Step-by-step debugging guide

When a payment is not becoming paid:

1. Open the payment intent detail page.
2. Confirm status is still PENDING and not EXPIRED.
3. Confirm the checkout amount matches the wallet payment amount.
4. Confirm the checkout receiver wallet matches the SMS receiverMsisdn.
5. Confirm the SMS reference matches customerReference.
6. Confirm the transaction ID is not already linked to another SMS event.
7. Open SMS Events and check parse/match status.
8. Use Reconciliation if the match is partial or ambiguous.

Why is my payment not matching?

Most failed matches are caused by one of these:

• wrong amount
• wrong merchant wallet number
• missing or different reference
• expired payment intent
• duplicate transaction ID
• sandbox/live environment mismatch
• Android SMS Agent did not send the SMS event

Does the SMS Simulator create payment intents?

No. The SMS Simulator only sends sandbox SMS events. Create a sandbox payment intent first, open checkout, then send a matching simulator SMS event.

What if the user pays late?

If the intent is expired, the gateway prevents auto-confirmation. Your operations team can inspect the SMS event and order manually, but your system should not auto-fulfill expired payments.

What if the user pays the wrong amount?

Wrong amount does not auto-confirm the payment. Depending on other matching signals, it may remain pending or move to REVIEW_REQUIRED.

What if the customer forgets the reference?

The instant match needs the reference. If the SMS has a valid transaction ID and the customer enters that transaction ID on checkout, fallback confirmation can still succeed when amount, receiver, active intent, and unused SMS checks pass.

What if two customers pay the same amount?

The reference and receiver prevent accidental matching. If data is ambiguous, the gateway routes to review instead of marking the wrong intent paid.

What if a webhook is delivered twice?

Webhook delivery is at-least-once. Store X-Webhook-Id or your own idempotency record keyed by payment intent and event type.

Code example

Safe fulfillment check:

async function fulfillFromWebhook(event: {
  event: string;
  data: { payment_intent_id: string; customer_reference: string };
}) {
  if (event.event !== "payment.paid") return;

  await db.transaction(async (tx) => {
    const order = await tx.orders.findUnique({
      where: { reference: event.data.customer_reference },
    });

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

    await tx.orders.update({
      where: { id: order.id },
      data: { status: "paid" },
    });
  });
}

Request and response samples

Check a payment intent:

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

{
  "id": "b5012f33-207e-4999-bf8d-5a1ebb10988e",
  "status": "REVIEW_REQUIRED",
  "amount": "500",
  "currency": "BDT",
  "customerReference": "ORDER-10045",
  "receiverMsisdn": "01700000001"
}

Edge cases and constraints

• Public checkout status is for display, not fulfillment.
• A transaction ID can confirm only one payment.
• Sandbox simulator cannot affect live payment intents.
• Live Android SMS events cannot affect sandbox payment intents.
• Create a new payment intent if the customer misses the 5-minute window.