Stuck top-ups
What to do with a top-up in status reconcile or review, or paid but not credited.
Online payments
In the account service, an online payment that is not finished stays pending. A background job asks the payment gateway about it again every few minutes, for up to 72 hours. Most stuck payments settle on their own.
| You see | What it means | What to do |
|---|---|---|
pending for a long time | The gateway has not confirmed yet. | Check the payment in the gateway dashboard. Then use Re-verify (admin API POST /admin/transactions/{id}/reverify). Never credit by hand. |
review | Paid, but amount, currency or reference does not match what was asked. | Check the gateway dashboard and talk to the customer. Credit the amount really received by hand only after that, with a note. |
success but the SMS balance did not go up | The payment is settled, but sending the credit to the SMS service failed. | Use Retry credit (admin API POST /admin/transactions/{id}/fanout-retry). Do not credit again by hand: that would pay twice. |
SMPP credits in status reconcile
Every SMPP credit (a top-up approval, a reseller transfer, a staff credit or an online payment) is a ledger entry. The service writes the entry first, then tells the SMPP gateway to change the bind's balance:
| Ledger status | Meaning | What to do |
|---|---|---|
applied | The gateway confirmed the change. | Nothing. |
failed | The gateway refused. Nothing changed. | Safe to try again with the same idempotency key. |
reconcile | The connection to the gateway was lost in the middle. Nobody knows if the balance changed. | Check by hand, then settle. It is never retried automatically. |
In the portal a reconcile entry, and its top-up request, show as being checked.
Never credit blindly
Crediting again without checking can give away free SMS, or credit the same money twice.
Steps
Open Ledger and note the entry: system_id, number of SMS and the time.
Read the bind's real balance in the gateway itself. On the server, open the jcli console of the SMPP gateway and run user -s <system_id>. Look at the SMS quota (mt_messaging_cred quota sms_count).
Compare with what you expect: the balance shown in the portal before the entry, plus the credit, less the segments the bind sent since (see Reports). If the gateway balance already includes the SMS, the credit happened: settle with outcome applied.
If the balance does not include them, the credit did not happen: settle with outcome failed. Then credit again with a new idempotency key, or approve the request again.
Settling needs a short note. It uses Ledger, Settle, or POST /api/v1/admin/ledger/{id}/settle with outcome and note.
If you are not sure, leave it and ask a second admin. Waiting is safe. Wrong credit is not.
If many are stuck
- Several online payments stuck at once usually mean the gateway or its webhook is down. Check the webhook URL in the gateway dashboard and the account service logs.
- Several SMPP entries in
reconcileat once usually mean the SMPP gateway restarted or its console was unreachable. Check the gateway is up and its users are loaded (see Rotating secrets, Jasmin console) before you settle them one by one.