18 Feb 20266 min readPayments · Webhooks · APIs

Trust the webhook, not the success screen

Payment UIs lie. Network drops, double taps, delayed redirects — if you credit wallets from the client, you will eventually pay someone twice.

The most expensive sentence in payments is “the client said it worked.”

Success screens lie. Tabs get closed. Retries happen. Redirects time out. If you credit a wallet because checkout looked finished, you will eventually double-credit someone — or miss a capture that actually succeeded.

Make the provider event the source of truth

The happy path I trust is boring on purpose: backend creates the order, client opens checkout, provider captures payment, webhook arrives, you verify the signature, then you write a ledger credit. The UI can celebrate early. Your database should not.

Signature verification is not optional ceremony. Without it, anyone who can hit your webhook URL can invent a payment. With it, the provider’s event becomes something you can actually trust.

Idempotency is the boring part that saves you

Users mash the button. Mobile networks retry. Your worker retries. Without an idempotency key on recharge — and unique provider payment IDs in your ledger — someone gets paid twice.

Webhook handlers must be safe to run twice and produce the same result. If the second delivery of the same event creates a second credit, the bug is in your design, not in the provider.

Prefer a ledger over a mutable balance

A single balance field is easy until the first dispute, refund, commission split, or tax question shows up. Then you want a trail, not a number you hope is right.

Settlement becomes a set of clear entries — recharge, debit, earning, commission, GST — instead of one mysterious update. Webhooks will still be late sometimes. Keep status polling and an admin verify path as backups, and be honest about which path is primary.

When support asks “did they pay?”, you want one answer — not three competing stories from the UI, the order table, and the wallet balance.