Paystack Popup in React and Next.js, then inside an animated cart drawer

Paystack's Popup is a payment window Paystack draws on top of your page. You don't build card fields for it. In React you load @paystack/inline-js on click, open the popup with an access code your server created, and check the payment on your server before you call it paid. This page does that in the Next.js App Router with typed server actions, adds the webhook, then wires the same popup to the Checkout button of an animated cart drawer.

One payment$3

By buying you agree to the Terms.

One payment, no subscription
Download right after paying
Use it in client projects
Won't run on the listed stack? We fix it or refund you

Ready forCursorv0Lovableshadcn CLI

Full product pageReact · Tailwind · TypeScript

Paystack Popup in Next.js with @paystack/inline-js

app/pay/paystack-button.tsx

"use client";
import { useState } from "react";
import { startPayment, verifyPayment } from "./actions";

type State = "idle" | "opening" | "paid" | "cancelled" | "failed";

export default function PaystackButton({ email }: { email: string }) {
  const [state, setState] = useState<State>("idle");

  async function pay() {
    setState("opening");
    try {
      // @paystack/inline-js reads window as soon as it loads, so import it here, on click.
      const { default: PaystackPop } = await import("@paystack/inline-js");
      // The server creates the transaction with your secret key and sends back an access code.
      const { accessCode, reference } = await startPayment(email);
      new PaystackPop().resumeTransaction(accessCode, {
        onSuccess: async () => setState((await verifyPayment(reference)) ? "paid" : "failed"),
        onCancel: () => setState("cancelled"),
        onError: () => setState("failed"),
      });
    } catch {
      setState("failed");
    }
  }

  return (
    <div className="space-y-3">
      <button
        type="button"
        onClick={pay}
        disabled={state === "opening" || state === "paid"}
        className="rounded-xl bg-emerald-500 px-5 py-3 font-semibold text-black disabled:opacity-60"
      >
        {state === "opening" ? "Opening Paystack..." : "Pay with Paystack"}
      </button>
      <p role="status" className="text-sm text-neutral-400">
        {state === "paid" && "Paid and verified on the server."}
        {state === "cancelled" && "You closed the payment window. Nothing was charged."}
        {state === "failed" && "That payment did not go through."}
      </p>
    </div>
  );
}

app/pay/actions.ts

"use server";
import { paystack, type Initialized, type Verified } from "@/lib/paystack";

// Set on the server, never by the browser. Paystack counts in the lowest unit: kobo for NGN.
const AMOUNT = 500000; // kobo
const CURRENCY = "NGN";

export async function startPayment(email: string) {
  const tx = await paystack<Initialized>("/transaction/initialize", {
    email,
    amount: String(AMOUNT),
    currency: CURRENCY,
  });
  return { accessCode: tx.access_code, reference: tx.reference };
}

export async function verifyPayment(reference: string) {
  const tx = await paystack<Verified>(`/transaction/verify/${encodeURIComponent(reference)}`);
  // The popup saying success is not proof. Check the status, the amount and the currency here.
  return tx.status === "success" && tx.amount === AMOUNT && tx.currency === CURRENCY;
}

lib/paystack.ts

// Server only. The secret key never reaches the browser.
const API = "https://api.paystack.co";

type Envelope<T> = { status: boolean; message: string; data: T };

export type Initialized = { authorization_url: string; access_code: string; reference: string };
export type Verified = { status: string; reference: string; amount: number; currency: string };

export async function paystack<T>(path: string, body?: Record<string, unknown>): Promise<T> {
  const res = await fetch(API + path, {
    method: body ? "POST" : "GET",
    headers: {
      Authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: body ? JSON.stringify(body) : undefined,
    cache: "no-store",
  });
  const json = (await res.json()) as Envelope<T>;
  // A wrong key, a bad amount or an unknown reference comes back with status false and a message.
  if (!res.ok || !json.status) throw new Error(json.message || `Paystack answered ${res.status}`);
  return json.data;
}

app/pay/page.tsx

import PaystackButton from "./paystack-button";

export default function PayPage() {
  // Use the signed in customer's email. Paystack sends the receipt there.
  return (
    <main className="mx-auto max-w-md p-6">
      <PaystackButton email="[email protected]" />
    </main>
  );
}

Good to know

We type-checked every snippet on Oct 26 2026 against @paystack/inline-js 2.27.0 (published Oct 22 2026), @types/paystack__inline-js 1.0.3, next 15.5.28, react 19.1.1 and TypeScript 5.9.3, then ran next build. Five wrong calls fail tsc as they should: newTransaction without amount, amount as a string on the client, a number as the access code, reading amount from the onSuccess data, and the import with the types package removed.
@paystack/inline-js ships no types of its own (no types field in its package.json). The types come from the community package @types/paystack__inline-js, so add it as a dev dependency: npm i -D @types/paystack__inline-js. It declares the class as a default export under esModuleInterop, which Next.js turns on.
Importing @paystack/inline-js on the server throws "window is not defined". We checked: requiring the package in plain Node stops on that line. So the import sits inside the click handler, where it only runs in the browser. A top level import in a "use client" file still runs during server rendering.
Paystack counts money in the lowest unit of the currency: kobo for NGN, pesewas for GHS, cents for ZAR and KES. The transaction API takes amount as a string in that unit; the popup's newTransaction takes a number. Set the amount on the server, never from the browser.
The popup calling onSuccess is not proof of payment. Paystack's docs say to verify: the server action calls GET /transaction/verify/:reference with your secret key and checks status, amount and currency. Fulfil orders from the charge.success webhook, which also arrives when the buyer closes the tab.
What we ran on Oct 26 2026: next build and next start in a clean Next.js 15 app. The real @paystack/inline-js with a made-up pk_test key opened Paystack's window from checkout.paystack.com, a full page iframe at z-index 2147483647 with a dark backdrop, which answered "We could not start this transaction. Please enter a valid Key" and fired onError with that message. The real server action sent transaction/initialize to api.paystack.co with a made-up secret key; Paystack answered "Invalid key", the action threw, and the button and the cart both showed the failure. With PaystackPop swapped for a stand-in that fires the same callbacks, the cart drawer called start, then resumeTransaction with the access code, then verify, folded its lines home and announced the order; on cancel it kept the cart open. No page errors from our code and no sideways scroll at 390 and 1440 wide.
What we didn't run: we have no Paystack account on this test, so no test key, no completed test payment, no real verify answer and no webhook delivery. The success path above ran against the stand-in.

newTransaction: the browser only route

The shortest way to open the popup is newTransaction with your public key, the customer's email and the amount. It is fine for a quick test with a pk_test key.
The catch: the amount lives in browser code, so anyone can change it before the popup opens. Keep the server action from the top of this page for real orders, or at least verify the amount on the server before you give anything away.
Paystack's README also lists preloadTransaction (load first, open later) and checkout, which shows a wallet step such as Apple Pay first where the device supports it. Both take the same options and are in the types package.

app/pay/simple/new-transaction.tsx (the browser only route)

"use client";
// The shortest route: everything in the browser with your public key.
// The amount is set here, so anyone can change it in devtools. Verify it on the server before you ship.
export function payInBrowser(email: string, onPaid: (reference: string) => void) {
  return import("@paystack/inline-js").then(({ default: PaystackPop }) => {
    new PaystackPop().newTransaction({
      key: process.env.NEXT_PUBLIC_PAYSTACK_PUBLIC_KEY!, // pk_test_... while you build
      email,
      amount: 500000, // kobo, the lowest NGN unit
      currency: "NGN",
      onSuccess: ({ reference }) => onPaid(reference),
      onCancel: () => console.info("Popup closed, nothing charged"),
      onError: ({ message }) => console.error("Paystack could not load the payment:", message),
    });
  });
}

Verify the payment on the server, then the webhook

verifyPayment in actions.ts calls GET https://api.paystack.co/transaction/verify/:reference with your secret key and returns true only for status success with the amount and currency you set. That is what decides whether the button says paid.
The webhook is the record you fulfil from. Paystack's webhook docs (read Oct 26 2026) say each event carries an x-paystack-signature header, an HMAC SHA512 of the payload signed with your secret key. The route reads the raw body as text, signs it, compares the two, and answers 200 fast.
Add the URL on your Paystack dashboard; localhost can't receive events. Paystack's docs say an event without a 200 OK is sent again (in live mode every 3 minutes for the first 4 tries, then hourly for 72 hours), so make the order update safe to run twice for the same reference.

app/api/paystack/webhook/route.ts

import { createHmac, timingSafeEqual } from "node:crypto";

// Paystack signs each event with your secret key: HMAC SHA512 of the raw body, hex, in x-paystack-signature.
export async function POST(req: Request) {
  const raw = await req.text();
  const sent = req.headers.get("x-paystack-signature") ?? "";
  const ours = createHmac("sha512", process.env.PAYSTACK_SECRET_KEY!).update(raw).digest("hex");
  if (sent.length !== ours.length || !timingSafeEqual(Buffer.from(sent), Buffer.from(ours))) {
    return new Response("bad signature", { status: 401 });
  }
  const event = JSON.parse(raw) as { event: string; data: { reference: string; amount: number; currency: string } };
  if (event.event === "charge.success") {
    // Mark the order paid here, once per reference. This runs even if the buyer closed the tab.
  }
  return new Response(null, { status: 200 });
}

TypeScript types for @paystack/inline-js

@paystack/inline-js 2.27.0 is plain JavaScript: its package.json has no types field and the tarball has no .d.ts files. Without help, TypeScript strict stops with "Could not find a declaration file for module '@paystack/inline-js'" (TS7016). We saw exactly that when we removed the types package.
@types/paystack__inline-js 1.0.3 (DefinitelyTyped, published June 3 2026) covers the constructor, newTransaction, resumeTransaction, cancelTransaction, preloadTransaction, checkout and paymentRequest, with the options and callback shapes. It is written by the community, not by Paystack.
Two small differences between the types and Paystack's README, both read Oct 26 2026: the README gives the transaction id in onSuccess as a number, the types say string, and the types add fields such as trxref and redirecturl. The snippets on this page only read reference, which both agree on.

react-paystack and React 19

react-paystack 6.0.0 is the latest version on npm, published Aug 4 2024. It exports usePaystackPayment, PaystackButton and PaystackConsumer, ships its own types, and depends on @paystack/inline-js ^2.19.2, so it uses the same popup underneath.
Its peerDependencies list react and react-dom from ^15.0.0 to ^18.0.0. A Next.js 15 app runs React 19, which is outside that range, so npm 7 or newer stops the install with a peer dependency conflict unless you pass --legacy-peer-deps.
We didn't type-check react-paystack against React 19, so this page uses @paystack/inline-js directly. The code is short, and you choose where the import happens and what onSuccess does.

Paystack Popup behind Stack Cart Drawer's Checkout button

Stack Cart Drawer calls onCheckout(items, total) when someone presses Checkout and shows Paying on the button while it waits. It awaits your promise: { ok: true } folds every line back into its disc, flies them home, closes the drawer and flashes a lime check with the order number; { ok: false } keeps the cart and announces that the payment failed.
So payWithPaystack starts the transaction on the server, opens Paystack's popup with the access code and only resolves when something happens in the popup. onSuccess asks your server to verify first. onCancel and onError resolve { ok: false }, so a closed popup leaves the cart exactly as it was.
Paystack's window opens on top of everything. It is a full page iframe at the highest z-index, so it covers the drawer and its backdrop while the customer pays, and the drawer's animation plays once the popup closes.
The server action prices the cart from its own table in kobo and ignores the drawer's total. It also sends the cart as metadata, which Paystack takes as a JSON string, so you see it on the transaction in your dashboard.
Three edits to know about. The drawer formats money in US dollars: change the Intl.NumberFormat line in engine.ts to en-NG and NGN, and the dollar sign in the odometer span in StackCartDrawer.tsx. The check shows data.shop.orderNo, a fixed string from your data, not Paystack's reference. And the failure line reads "Payment failed. Nothing was charged.": true for a cancel, not when your server rejects a reference Paystack called a success, so change that line in engine.ts if you want different words there.

app/shop/page.tsx

"use client";
import StackCartDrawer from "@/components/StackCartDrawer";
import { startCartPayment, verifyCartPayment } from "./actions";

type Line = { id: string; qty: number };

// The drawer awaits this. { ok: true } folds the lines home and flashes the check, { ok: false } keeps the cart.
async function payWithPaystack(items: Line[]): Promise<{ ok: boolean }> {
  const { default: PaystackPop } = await import("@paystack/inline-js");
  const { accessCode, reference } = await startCartPayment(items, "[email protected]");
  return new Promise((resolve) => {
    new PaystackPop().resumeTransaction(accessCode, {
      // Paystack says paid. Ask your server before the drawer celebrates.
      onSuccess: () => {
        verifyCartPayment(reference, items).then((ok) => resolve({ ok }), () => resolve({ ok: false }));
      },
      onCancel: () => resolve({ ok: false }),
      onError: () => resolve({ ok: false }),
    });
  });
}

export default function Shop() {
  return (
    <div className="h-dvh">
      <StackCartDrawer
        autoplayDemo={false}
        onCheckout={(items) => payWithPaystack(items).catch(() => ({ ok: false }))}
      />
    </div>
  );
}

app/shop/actions.ts

"use server";
import { paystack, type Initialized, type Verified } from "@/lib/paystack";

// Prices live on the server, in kobo (the drawer's price times 100). The drawer's total is only for the screen.
const KOBO: Record<string, number> = { orbit: 18900, case: 2400, cable: 1900 };
type Line = { id: string; qty: number };

const totalOf = (items: Line[]) => items.reduce((sum, i) => sum + (KOBO[i.id] ?? NaN) * i.qty, 0);

export async function startCartPayment(items: Line[], email: string) {
  const amount = totalOf(items);
  if (!Number.isInteger(amount) || amount <= 0) throw new Error("Unknown product in the cart");
  const tx = await paystack<Initialized>("/transaction/initialize", {
    email,
    amount: String(amount),
    currency: "NGN",
    metadata: JSON.stringify({ cart: items }), // Paystack takes metadata as a JSON string
  });
  return { accessCode: tx.access_code, reference: tx.reference };
}

export async function verifyCartPayment(reference: string, items: Line[]) {
  const tx = await paystack<Verified>(`/transaction/verify/${encodeURIComponent(reference)}`);
  return tx.status === "success" && tx.currency === "NGN" && tx.amount === totalOf(items);
}

The popup is Paystack's own page from checkout.paystack.com in an iframe over your site: a dark backdrop over the whole page, a white card in the middle and "Secured by paystack" under it. With our made-up key the card said "We could not start this transaction. Please enter a valid Key". With a real key it shows the payment options there.
You can't restyle anything inside it with CSS or props. What you control in code is which channels it offers (channels, such as card, bank_transfer, ussd or mobile_money), the currency and the customer's email. Your business details come from your Paystack account settings.
That is why the animation on this page lives around the popup, in the cart and its confirmation, and not in the payment form itself.

Scope the cart's CSS before the Paystack checkout goes live in a shadcn app

One thing to fix before this goes into a shadcn or other Tailwind UI kit app: cart-drawer.css is global as it ships. It puts colour variables like --muted on :root, gives html and body a dark theme, and has unprefixed classes like .grid.
Measured October 25, 2026 in a shadcn app on Tailwind v4: the whole app went dark in Space Grotesk, --muted changed everywhere, two column grids became three columns with a 30px gap, and Buttons went from 14px at weight 500 to 16px at weight 400.
Scope your copy to the cart: one @scope (.qcd) block around the file, :scope instead of :root and html,body, the 9 html:not(.fit) prefixes gone, three rules in globals.css and a qcd div around the component. The Paystack wiring above stays the same. The shadcn cart drawer guide ("A shadcn cart drawer for Next.js", under More for React) explains every line; this page didn't re-measure it.
Browser support for @scope, from MDN's compatibility data read October 25, 2026: Chrome and Edge 118+, Firefox 146+, Safari 17.4+ on Mac and iPhone. Safari 26.0 to 26.3 has a partial version that skips input and textarea elements; the cart has neither. Browsers without @scope drop the block and show the cart unstyled.
If that matters for your buyers, use a prefix instead: .qcd in front of every selector. We haven't measured it.

components/cart-drawer.css (your copy, three edits)

/* Your copy of cart-drawer.css from the zip. Three edits: */

/* 1. Delete every "html:not(.fit) " prefix.
      There are 9, all inside the max-width: 760px block. */

/* 2. ":root{" becomes ":scope{", and "html,body{" becomes ":scope{". */

/* 3. Put the whole file inside one @scope block: */
@scope (.qcd) {
  /* ...the file as shipped, with edits 1 and 2... */
}

app/globals.css (three rules for the cart)

/* Add below shadcn's theme and @layer base in app/globals.css */
/* Stack Cart Drawer was built with Tailwind's preflight off. Inside .qcd only,
   roll the base styles (preflight and shadcn's base layer) back to browser
   defaults. Unlayered and zero specificity, so the piece's own rules still win.
   SVGs are left out: a revert would wipe their width, r, fill and stroke. */
:where(.qcd, .qcd :not(svg, svg *)) {
  all: revert;
}
:where(.qcd) {
  line-height: normal;
}
:where(.qcd svg) {
  display: inline;
  vertical-align: baseline;
}

app/shop/page.tsx (the wrapper)

// app/shop/page.tsx: payWithPaystack stays the same; only the div is new.
return (
  <div className="qcd">
    <StackCartDrawer /* ...the props above, unchanged... */ />
  </div>
);

components/cart-drawer.css (fallback for browsers without @scope)

/* No @scope block. Keep edit 1 (delete "html:not(.fit) "), then put .qcd
   in front of every selector, each part of a comma list included: */
.qcd{ /* was :root{ ...the colour and font variables... */ }
.qcd *{box-sizing:border-box}
.qcd{ /* was html,body{ ...margin, background, colour, font... */ }
.qcd .grid{ /* ...as shipped... */ }
/* ...and so on to the end of the file. The globals.css rules stay as they are. */

Install

Copy from the zipPut react/src/components + react/src/data into src/, then npm i framer-motion @paystack/inline-js && npm i -D @types/paystack__inline-js.
Or ask your AIPaste PROMPT.md into Cursor, Lovable or v0.

Props

onCheckout: (items, total) → { ok }: open Paystack's popup, resolve after your server verifies
data: store name, products, free shipping line, orderNo for the check
autoplayDemo: false for a real shop

How qodesign compares

qodesign vs 21st.dev21st.dev is best for: browsing a huge marketplace and copying many components a month.
qodesign vs Skiper UISkiper UI is best for: unusual interaction details for landing pages: image reveals, cursor trails, tooltips, drag-and-scroll galleries.

All comparisons, with prices read on each library's own site.

From the blog: Slide-Out Cart Drawer in React With Native dialog

Questions

Which keys do I use while building?

Your test keys from the Paystack dashboard: pk_test for the browser, sk_test for the server. Test mode never moves real money. Paystack's docs have a Test Payments page with test cards; it sat behind a bot check when we tried to read it on Oct 26 2026, so we don't quote them here.

Why is the amount so big?

Paystack wants the lowest unit of the currency: kobo for NGN, pesewas for GHS, cents for ZAR and KES. 100 kobo make one naira, so multiply by 100. On transaction/initialize the amount goes as a string; in the popup's newTransaction it is a number.

The popup doesn't open. What do I check?

Is the import inside the click handler, so it only runs in the browser? Did startPayment throw (a wrong or missing secret key comes back as "Invalid key")? Is the access code used once? Add onError to resumeTransaction: it gets Paystack's message, like "Please enter a valid Key" in our test.

Can I style the Paystack popup?

No. It is Paystack's page in an iframe. You pick channels, currency and the email in code; the rest stays as Paystack draws it.

Do I need react-paystack?

No. It wraps the same @paystack/inline-js. Its 6.0.0 release lists React up to 18 as a peer, so in a React 19 app the direct import on this page is the simpler route.

Will the cart drawer change my shadcn styles?

Only if you import cart-drawer.css as it ships. The @scope edit and the globals.css rules on this page keep it inside the cart's own div.

Can Cursor or v0 add it for me?

Yes. Each download has a PROMPT.md. Paste it into Cursor, Lovable, v0 or Claude Code and it fits the piece into your app.

Can I use it in client work?

Yes, in personal and client projects. You can't resell the code itself as a kit.

Paystack Popup in React and Next.js, then inside an animated cart drawer

Paystack Popup in Next.js with @paystack/inline-js

Good to know

newTransaction: the browser only route

Verify the payment on the server, then the webhook

TypeScript types for @paystack/inline-js

react-paystack and React 19

Paystack Popup behind Stack Cart Drawer's Checkout button

What Paystack's popup looks like, and what you can change

Scope the cart's CSS before the Paystack checkout goes live in a shadcn app

Install

Props

How qodesign compares

Questions

Paystack Popup in Next.js with @paystack/inline-js

Good to know

newTransaction: the browser only route

Verify the payment on the server, then the webhook

TypeScript types for @paystack/inline-js

react-paystack and React 19

Paystack Popup behind Stack Cart Drawer's Checkout button

What Paystack's popup looks like, and what you can change

Scope the cart's CSS before the Paystack checkout goes live in a shadcn app

Install

Props

How qodesign compares

Questions