Accepting payments in Next.js: a complete guide

# Server only. No NEXT_PUBLIC_ prefix, so it is never sent to the browser.
PAYMENTS_SECRET_KEY=sk_...
WEBHOOK_SIGNING_SECRET=whsec_...

# Safe in the browser by design — these two are needed to build the card form.
NEXT_PUBLIC_PAYMENTS_PUBLISHABLE_KEY=pk_...
NEXT_PUBLIC_PAYMENTS_ACCOUNT_ID=acct_...

export async function POST(request) {
  const { orderId } = await request.json();

  // The amount comes from your own records, never from the request body.
  // A client-supplied total is a client-controlled price.
  const order = await db.orders.findById(orderId);
  if (!order) return Response.json({ error: "Unknown order" }, { status: 404 });

  const response = await fetch("https://api.sandbox-paymentsonline.io/v1/payment-intents", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payments-api-key": process.env.PAYMENTS_SECRET_KEY,
      "payments-account": process.env.NEXT_PUBLIC_PAYMENTS_ACCOUNT_ID,
    },
    body: JSON.stringify({
      amount: order.totalCents,        // minor units: 2500 is $25.00
      currency: "usd",
      payment_method_types: ["card"],
      metadata: { order_id: order.id },  // makes the payment findable later
    }),
  });

  const intent = await response.json();
  if (!response.ok) {
    // message is a string OR an array of strings. Flatten both.
    const detail = [].concat(intent?.message ?? []).join("; ");
    return Response.json({ error: detail }, { status: 502 });
  }

  // Only the client_secret crosses to the browser.
  return Response.json({ clientSecret: intent.client_secret });
}

"use client";

import { useEffect, useRef, useState } from "react";

export default function PayForm({ orderId }) {
  const [status, setStatus] = useState("loading");
  const paymentsRef = useRef(null);
  const formRef = useRef(null);

  useEffect(() => {
    let cancelled = false;

    (async () => {
      await loadScript("https://js.paymentsonline.io/v2");
      if (cancelled) return;

      const payments = new window.Payments(
        process.env.NEXT_PUBLIC_PAYMENTS_PUBLISHABLE_KEY,
        process.env.NEXT_PUBLIC_PAYMENTS_ACCOUNT_ID,
        { sandbox: true },
      );

      // form(), not createForm().
      const form = await payments.form({ payment_method_type: "card" });
      form.createField("cardNumber").inject("#card-number");
      form.createField("cardExpiry").inject("#card-expiry");
      form.createField("cardCvv").inject("#card-cvv");
      await form.build();

      paymentsRef.current = payments;
      formRef.current = form;
      if (!cancelled) setStatus("ready");
    })();

    // Strict Mode mounts effects twice in development. Without a teardown the
    // second mount injects a second set of fields into the same containers.
    return () => {
      cancelled = true;
      formRef.current?.teardown?.();
    };
  }, []);

  async function handleSubmit(event) {
    event.preventDefault();
    setStatus("submitting");

    // Fetch the client_secret now, not on page load — see the note below.
    const res = await fetch("/api/checkout", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ orderId }),
    });
    const { clientSecret, error } = await res.json();
    if (error) return setStatus("error");

    const payments = paymentsRef.current;

    // Tokenize on submit. An unattached payment method expires in 15 minutes.
    const paymentMethod = await payments.createPaymentMethod({
      type: "card",
      billing_details: { name: "Ada Lovelace", address: { zip: "80021", country: "US" } },
    });

    const result = await payments.confirmPayment(clientSecret, paymentMethod);

    // A 2xx does not mean the money moved. Read the status.
    setStatus(result?.status === "succeeded" ? "succeeded" : "declined");
  }

  return (
    <form onSubmit={handleSubmit}>
      <div id="card-number" />
      <div id="card-expiry" />
      <div id="card-cvv" />
      <button type="submit" disabled={status !== "ready"}>
        {status === "submitting" ? "Paying…" : "Pay"}
      </button>
    </form>
  );
}

import crypto from "node:crypto";

export async function POST(request) {
  const raw = await request.text();            // raw bytes, before parsing
  const header = request.headers.get("payments-signature") ?? "";

  if (!verify(raw, header, process.env.WEBHOOK_SIGNING_SECRET)) {
    return new Response("bad signature", { status: 400 });
  }

  const event = JSON.parse(raw);

  // Retries mean this can arrive more than once. Key on the event id.
  const fresh = await db.processedEvents.claim(event.id);
  if (!fresh) return new Response("ok", { status: 200 });

  if (event.type === "payment_intent.succeeded") {
    await fulfilOrder(event.data.metadata.order_id);
  }

  // Acknowledge fast. Slow work here is recorded as a failed delivery.
  return new Response("ok", { status: 200 });
}