Accept payments
Matching rules
How SMS, references and claims settle a payment.
Every incoming SMS and every claim runs through the same matching engine inside a serializable database transaction with row locks, so concurrent SMS and claims cannot double-credit.
When an SMS arrives#
- The SMS is parsed and stored by
(network, Transaction ID). Re-sent SMS are recognised and ignored. - If a payment has claimed this Transaction ID and is waiting, it is settled with this SMS.
- Otherwise, if the SMS contains a short reference (the
LPmarker anywhere in an 8-character token), the payment with that reference is settled — while it is pending, or expired but still inside the claim window. - Otherwise the SMS waits as Unclaimed until a customer claims it or an admin uses it in a review.
Settling a payment#
A payment is verified only if all checks pass; otherwise it goes to review with the reason:
- The SMS isn’t much older than the payment (oldest claimable SMS).
- The SMS isn’t ignored.
- The reference in the SMS, if any, belongs to this payment; a reference typed with the claim agrees with the SMS.
- The amount satisfies the payment’s amount policy.
Amount policies#
| Policy | Accepts | Typical use |
|---|---|---|
AT_LEAST | The amount due or more (default). | Orders, invoices, payment links. |
EXACT | Exactly the amount due. | Accounting that cannot accept overpayments. |
ANY | Any amount; you are told what arrived. | Wallet top-ups, donations, bare claims. |
The SMS amount is always the truth: receivedAmountPesewas on the verified payment is what actually arrived.
Windows#
| Setting (Settings → Matching) | Default | Meaning |
|---|---|---|
| Reference auto-match | 60 min | How long a payment stays PENDING. Override per payment with expiresInMinutes. |
| Wait for SMS after a claim | 6 h | CLAIM_SUBMITTED becomes REVIEW after this. |
| Customers can claim for | 72 h | After this the payment can no longer be claimed. |
| Oldest claimable SMS | 72 h | An SMS older than this before the payment was created cannot verify it. |
Expiry is not failure
When the reference window ends the payment becomes EXPIRED and you receive payment.expired. A late SMS with its reference, or a claim with the Transaction ID, can still verify it during the claim window — so don’t cancel orders on expiry alone if you want to accept late payers.