Integrating Paystack Webhooks Into a Nigeria Store: 2026 Guide

The verdict in three sentences

The Paystack API sends a charge.success event signed with HMAC-SHA512 that you must verify before delivering any order. Without idempotency and a replay queue, a single HTTP 500 from your server drops the event and leaves the order pending. This guide covers the full integration, from the sandbox-to-production switch to exponential retry across 3 attempts within 24 hours.

Anatomy of the Paystack integration

Paystack exposes a clean REST API: you call POST /transaction/initialize with the amount (in kobo), currency NGN and a unique reference (your order number). Paystack returns an authorization_url to redirect the customer to. Once payment succeeds, Paystack notifies your server via a charge.success webhook.

The critical point: every webhook carries an x-paystack-signature header that you must recompute with HMAC-SHA512 and your secret key before trusting the event. Never deliver an order based on the browser redirect alone.

On fees, plan for a ballpark of 1.5% per local-card transaction on a Paystack merchant account in 2026. On an order of NGN 25,000, that is about NGN 375 in fees.

Idempotency, signature and retry

The golden rule: your webhook endpoint must handle the same event twice without creating two orders. Store the event id; if already processed, respond 200 OK immediately without re-running business logic.

For robustness, separate the inbound webhook (which Paystack replays) from your own processing queue. If your database is down, deliberately return 500: Paystack will replay. Let's compare Paystack Nigeria and Wave Cote d'Ivoire, two signed but different approaches.

Implement exponential retry on the processing side: attempt 1 immediate, attempt 2 after 30 minutes, attempt 3 after several hours, then abort and alert beyond 24 hours.

Mini case study

Chidi runs a sneaker store in Lagos (Lekki). Before a proper integration he delivered on browser redirect: 4% of his 300 monthly orders stayed "pending" for lack of reliable confirmation, i.e. 12 stuck orders. After adding the signed webhook + idempotency + retry over 24 h, the unconfirmed rate drops to 0.3%, under one order per month. On an average basket of NGN 45,000 equivalent, he recovers about 11 x 45,000 = NGN 495,000 of previously phantom revenue each month, for a one-off integration cost of around NGN 350,000 recouped in three weeks.

FAQ

Must I verify the Paystack webhook signature? Yes, always. An attacker could forge a fake charge.success. The HMAC-SHA512 check with your secret key guarantees the event truly comes from Paystack.

What if my server returns HTTP 500 during maintenance? No harm: Paystack treats it as a failure and replays the event (up to ~72 h). That is exactly why idempotency must come before any replay handling.

How do I move from sandbox to production? Swap your sk_test keys for sk_live, update the production webhook URL (HTTPS required) and replay at least one real NGN 100 scenario before opening to customers.

Is status polling useful if the webhook works? Yes, as a safety net. A cron that polls transactions left "pending" every 15 minutes catches the rare webhooks lost on unstable networks.

How much does the integration really cost? For a standard store, plan a ballpark of NGN 350,000 to 600,000 depending on complexity, excluding Paystack fees of ~1.5% per transaction.

Let's talk about your project. We integrate Paystack, Wave and Orange Money with signed webhooks, idempotency and retry tested in production. WhatsApp +221 77 596 93 33.