Integrating the Paystack API into a Next.js Checkout in Nigeria: 2026 Guide

The verdict in three sentences

Integrating Paystack into a Next.js checkout is not about showing a button: it is about initializing the transaction server-side, redirecting, then verifying the reference before any fulfillment. The golden rule for 2026: never trust the browser callback, always confirm with a verify call using your secret key. Amounts are sent in kobo (100 kobo = 1 NGN), fees are deducted at source, and without server verification you ship unpaid orders.

The Paystack flow end to end

The cycle is simple but each step has a trap. You call the API from a server route (never the client, your secret key must never ship in the bundle), Paystack returns an authorization URL, you redirect, the customer pays, then you confirm with the transaction reference.

The critical point is step 5. The browser callback can be faked or interrupted (the customer closes the tab). The only source of truth is the server call that queries Paystack with your secret key.

Endpoints, amounts and common error codes 2026

Here are the concrete parameters to know before coding, as 2026 order-of-magnitude figures.

In code, your verify route looks like this (pseudo-code): const tx = await fetch("https://api.paystack.co/transaction/verify/" + reference, { headers: { Authorization: "Bearer " + process.env.PAYSTACK_SECRET } }); if (tx.data.status === "success") { await fulfillOrder(orderId); }. You store the state in the database and make the operation idempotent: an already completed fulfillment must never replay.

Mini case study

Chidi, who runs a cosmetics shop in Lagos, sells an average basket of 12,000 NGN. On 300 orders a month, he had 12 disputes of the "I paid but got nothing" kind. Digging in, we found his old system fulfilled on the browser callback: when the network dropped after payment, the order shipped anyway, sometimes with no real payment. After switching to server verification (mandatory verify before fulfillment), disputes fell to 1 a month. On a 12,000 NGN basket, avoiding just 8 unpaid fulfillments a month saves 96,000 NGN of goods every month.

FAQ

In what unit are Paystack amounts sent in 2026?

In kobo, where 100 kobo equals 1 NGN. An amount of 5,000 NGN is sent as 500000. Always use integers, never decimals.

Can I fulfill on the browser callback alone?

No, never. The callback_url return can be interrupted or faked. Always run a verify call with your secret key and fulfill only if the status is success.

Are Paystack fees added on top or deducted at source?

Deducted at source in 2026. The customer pays the full amount and the fee (~1.5 % order of magnitude) is taken from the settlement. Reconcile your payouts accordingly.

How long does a clean Paystack Next.js integration take?

As a 2026 order of magnitude, budget 3 to 5 days for a robust checkout with server verification, error handling and a backup webhook. A prototype without guardrails takes a day but should not go to production.

Does the webhook replace the verify call?

No, they complement each other. The verify call confirms at the moment of return; the webhook catches cases where the customer closed the tab. Both must be idempotent.

Let's talk about your project. We integrate Paystack into your Next.js checkout with server verification, webhooks and full test coverage. WhatsApp +221 77 596 93 33.