You're offline — reconnect to continue buying or checking your wallet.
Core concepts

Webhooks

Payment gateways notify TopupRelay asynchronously when a funding attempt completes, that webhook, not your own redirect handler, is what actually credits a wallet. You don't receive these webhooks directly today; this page documents how TopupRelay itself verifies them, since the same pattern applies if you're building your own callback handling around a purchase.

Signature verification

Every inbound webhook is signature-verified before it's allowed to touch a balance, an unsigned or incorrectly signed payload is rejected with a 401 and never reaches the crediting logic.

POST /webhooks/{gateway}
Header: a gateway-specific signature header (e.g. x-paystack-signature)

expected = HMAC-SHA256(raw_request_body, gateway_webhook_secret)
reject unless constant-time-equal(expected, provided_signature)

Idempotency

Gateways retry webhook delivery on anything but a clean response, so the same event can arrive more than once. Crediting is an atomic compare-and-swap, a funding record can only move from pending to success once, so a duplicate delivery is a no-op rather than a second credit.

If you're polling instead

GET /wallet/fund/verify/{reference} (see Wallet & funding) is safe to call repeatedly from your own redirect handler as a fallback, it's idempotent against the same underlying funding record the webhook updates.