FAQ and Troubleshooting

Payment is not becoming paid

Check these in order:

1. Open Dashboard -> Payment Intents and confirm the intent is still PENDING.
2. Confirm the customer paid the exact checkout amount.
3. Confirm the customer paid to the checkout receiver number.
4. Confirm the wallet SMS arrived on the Android phone linked to SMS Pay.
5. Confirm the SMS reference matches the checkout customerReference.
6. Confirm the transaction ID was not already used.
7. Open SMS Events and inspect parse and match status.
8. Use Reconciliation when the evidence needs manual review.

What is the difference between references?

Recommended pattern:

• Let SMS Pay generate customerReference.
• Send your order number as merchantReference.
• Use payment_intent_${order.id} as idempotencyKey.

Why do I get customerReference must be shorter than or equal to 16 characters?

Your integration is probably sending a long order number as customerReference, for example ORD-1779771263742-7236.

Fix the payment intent request so the long order number is sent as merchantReference, and omit customerReference unless you have a short provider-safe code:

{
  "amount": 500,
  "currency": "BDT",
  "merchantReference": "ORD-1779771263742-7236",
  "idempotencyKey": "payment_intent_15aa64a2-92a5-4bf4-a54d-d7d27f373760"
}

SMS Pay will generate a short customerReference like SP7A91BC2D0 and return it in the response. Show/use that short value for wallet payment reference matching.

The Android device is offline

Check:

• the phone has internet access
• the SMS Pay app is open or allowed to run in background
• battery optimization is not stopping the app
• the device is linked to the correct merchant and environment
• the phone is receiving SMS for the configured receiver wallet

SMS is visible but payment did not match

Most matching failures are caused by:

• wrong amount
• wrong receiver wallet
• missing or different reference
• wrong payment method
• expired payment intent
• duplicate transaction ID
• sandbox/live mismatch

Use SMS Events and Reconciliation to inspect parsed amount, parsed reference, parsed TrxID, receiver, and match reason.

Customer paid late

If the payment intent expired before confirmation, SMS Pay will not auto-confirm it. Review the SMS evidence if needed, but your backend should not automatically fulfill expired payments. Create a new payment intent for customer retry.

Customer paid the wrong amount

Wrong amount does not become paid automatically. If the reference or TrxID identifies the payment evidence, the payment may move to REVIEW_REQUIRED. Merchant admins should review the evidence and decide the operational outcome.

Webhook was not delivered

Check Dashboard -> Webhooks:

• endpoint is active
• endpoint is verified
• endpoint is subscribed to the event
• URL is reachable from the internet
• production URL uses HTTPS
• your server returns 2xx
• signature verification uses the raw request body

Retry the delivery after fixing your endpoint.

Webhook delivered twice

Webhook delivery is at least once. Store X-Webhook-Id or X-Webhook-Idempotency-Key and make your fulfillment transaction idempotent. If the order is already paid, return 200 again.

Can I fulfill from successUrl?

No. successUrl is a browser redirect for customer experience. Fulfill only from a signed payment.paid webhook or from your backend retrieving the payment intent and confirming status === "PAID".

Can sandbox affect live payments?

No. Sandbox API keys, payment intents, SMS simulator events, and webhook tests are separate from live data. Live payments require live API keys and live Android device SMS evidence.