Next.js Integration

Wire a Next.js App Router app to Macropay end to end: create something to sell, send buyers to checkout, and react to paid orders — all in about five minutes. Because Macropay acts as your Merchant of Record, you never touch the parts that usually slow a launch down: we are the seller on the customer’s statement, we calculate and remit sales tax and VAT worldwide, and card data stays inside our PCI DSS Level 1 compliant vault. You write app logic; we own the tax and compliance liability.

Build against the Sandbox environment first. It mirrors production exactly but moves no real money, so you can replay checkouts and webhooks freely.

What you’ll need

A Macropay account with an organization
Next.js 14 or newer, using the App Router
An organization access token (OAT)

Install the SDK

Add the SDK, the React checkout component, and the webhook verifier:

npm install @macropayments/sdk @macropayments/checkout standardwebhooks

pnpm add @macropayments/sdk @macropayments/checkout standardwebhooks

yarn add @macropayments/sdk @macropayments/checkout standardwebhooks

Drop your credentials into .env.local:

MACROPAY_ACCESS_TOKEN="macropay_oat_your_token_here"
MACROPAY_WEBHOOK_SECRET="whsec_your_secret_here"

Create a product

In Macropay, everything you sell is a product — one-time or recurring share the same API and data model, only the pricing differs. Spin one up in the dashboard or straight from code. Here’s a monthly subscription priced at $24:

import { Macropay } from "@macropayments/sdk";

const macropay = new Macropay({
  accessToken: process.env.MACROPAY_ACCESS_TOKEN!,
  server: "sandbox",
});

const product = await macropay.products.create({
  name: "Analytics Pro",
  prices: [
    {
      type: "recurring",
      recurringInterval: "month",
      priceAmount: 2400, // amounts are in cents
      priceCurrency: "usd",
    },
  ],
});

console.log("Product ID:", product.id);

Need usage-based, seat-based, free, or pay-what-you-want pricing instead? Swap the prices array — the rest of this guide is identical. See pricing models for the full set.

Keep the product.id; the next step needs it.

Send buyers to checkout

A route handler is the cleanest way to mint a checkout on demand. It takes a product ID, opens a hosted checkout session, and redirects the buyer:

// src/app/checkout/route.ts
import { NextRequest, NextResponse } from "next/server";
import { Macropay } from "@macropayments/sdk";

const macropay = new Macropay({
  accessToken: process.env.MACROPAY_ACCESS_TOKEN!,
  server: "sandbox",
});

export async function GET(req: NextRequest) {
  const productId = req.nextUrl.searchParams.get("productId");
  if (!productId) {
    return NextResponse.json({ error: "productId required" }, { status: 400 });
  }

  const checkout = await macropay.checkouts.create({
    productId,
    successUrl: "https://your-app.com/welcome?checkout_id={CHECKOUT_ID}",
  });

  return NextResponse.redirect(checkout.url);
}

Point your pricing page at the route and pass the product ID through:

<a href="/checkout?productId=prod_xxx">Start Analytics Pro</a>

The hosted page handles currency localization, theming, and tax collection automatically — VAT and sales tax appear at the right rate for the buyer’s country with no extra work on your side.

Embed checkout inline (optional)

To keep buyers on your own page, render the checkout component instead of redirecting:

// src/app/pricing/page.tsx
"use client";

import { MacropayCheckout } from "@macropayments/checkout";

export default function PricingPage() {
  return (
    <MacropayCheckout
      productId="prod_xxx"
      successUrl="/welcome"
    />
  );
}

For theming, prefilled fields, and other options, see the embedded checkout reference.

Listen for webhooks

Webhooks are how your app learns a payment succeeded so it can grant access. Every Macropay webhook is signed using the Standard Webhooks spec — verify the signature with the standardwebhooks library before trusting the payload:

// src/app/api/webhooks/macropay/route.ts
import { NextRequest, NextResponse } from "next/server";
import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.MACROPAY_WEBHOOK_SECRET!);

export async function POST(req: NextRequest) {
  const body = await req.text();
  const headers = {
    "webhook-id": req.headers.get("webhook-id")!,
    "webhook-timestamp": req.headers.get("webhook-timestamp")!,
    "webhook-signature": req.headers.get("webhook-signature")!,
  };

  let payload: any;
  try {
    payload = wh.verify(body, headers);
  } catch {
    return NextResponse.json({ error: "invalid signature" }, { status: 401 });
  }

  switch (payload.type) {
    case "order.paid":
      // Grant access, update your database, send a receipt
      console.log("Order paid:", payload.data.id);
      break;
    case "subscription.created":
      console.log("New subscription:", payload.data.id);
      break;
    case "subscription.canceled":
      // Revoke access at period end
      console.log("Subscription canceled:", payload.data.id);
      break;
  }

  return NextResponse.json({ received: true });
}

Register the endpoint in the dashboard under Settings → Webhooks, then read the body as raw text (as above) — parsing JSON first will break signature verification. For local development, tunnel your dev server with ngrok: ngrok http 3000.

The full catalog of event types lives in the webhook events reference.

Test in the sandbox

Open your checkout page in the browser.
Pay with the test card 4242 4242 4242 4242, any future expiry, any CVC.
Confirm you land on your successUrl.
Watch the order.paid event arrive in your terminal.

Going to production

Three changes flip you from test to live:

Sandbox	Production
`macropay_oat_...` sandbox token	production OAT from the live dashboard
`server: "sandbox"`	`server: "production"` (or omit the field)
Sandbox webhook endpoint	Production endpoint URL registered in Settings → Webhooks

Once live, every order automatically carries the correct tax, settles into your Macropay balance, and pays out via ACH or SEPA at no fee. Disputes and chargebacks are handled for you as part of the Merchant of Record service.

Where to go next

All webhook events

Every event type your app can react to

Customer portal

A self-serve page for managing subscriptions

Meter AI & agent usage

Bill by tokens, activity, or outcome — and track agent ROI

Embedded checkout

Theming, prefills, and advanced options

Bootup

Features

Integrate

Merchant of Record (MoR)

Next.js Integration

What you’ll need

Install the SDK

Going to production

Where to go next

All webhook events

Customer portal

Meter AI & agent usage

Embedded checkout

​What you’ll need

​Install the SDK

​Going to production

​Where to go next

All webhook events

Customer portal

Meter AI & agent usage

Embedded checkout

What you’ll need

Install the SDK

Going to production

Where to go next