​
Prerequisites

We recommend using the Sandbox environment for this guide so you can test without processing real payments.

​
Step 1: Install Dependencies

npm install @macropay/sdk @macropay/nextjs @macropay/checkout
Add your credentials to .env.local: 
MACROPAY_ACCESS_TOKEN="macropay_oat_your_token_here"
MACROPAY_WEBHOOK_SECRET="whsec_your_secret_here"

​
Step 2: Create a Product

Create a product in the Macropay dashboard or via the API: 
import { Macropay } from "@macropay/sdk";

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

const product = await macropay.products.create({
  name: "Pro Plan",
  prices: [
    {
      type: "recurring",
      recurringInterval: "month",
      priceAmount: 1999,
      priceCurrency: "usd",
    },
  ],
});

console.log("Product ID:", product.id);
Copy the product.id — you will need it in the next step. Create a checkout link in the dashboard under your product, or generate one via the API. You can also create dynamic checkout sessions from a route handler: 
// src/app/checkout/route.ts
import { Checkout } from "@macropay/nextjs";

export const GET = Checkout({
  accessToken: process.env.MACROPAY_ACCESS_TOKEN!,
  successUrl: "https://your-app.com/thank-you?checkout_id={CHECKOUT_ID}",
  server: "sandbox",
});
Link to this route from your pricing page, passing the product ID as a query parameter: 
<a href="/checkout?productId=prod_xxx">Subscribe to Pro</a>

​
Step 4: Embed Checkout on Your Page

For a seamless experience, embed the checkout directly on your page instead of redirecting: 
// src/app/pricing/page.tsx
"use client";

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

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

​
Step 5: Handle Webhooks

Set up a webhook endpoint to process payment events. The @macropay/nextjs adapter handles signature verification automatically. 
// src/app/api/webhooks/macropay/route.ts
import { Webhooks } from "@macropay/nextjs";

export const POST = Webhooks({
  webhookSecret: process.env.MACROPAY_WEBHOOK_SECRET!,
  onPayload: async (payload) => {
    console.log("Received event:", payload.type);
  },
  onOrderPaid: async (order) => {
    // Provision access, update database, send confirmation email
    console.log("Order paid:", order.id);
  },
  onSubscriptionCreated: async (subscription) => {
    // Grant access to your product
    console.log("New subscription:", subscription.id);
  },
  onSubscriptionCanceled: async (subscription) => {
    // Revoke access
    console.log("Subscription canceled:", subscription.id);
  },
});
Register your webhook endpoint in the Macropay dashboard under Settings > Webhooks. For local development, use ngrok to expose your local server: ngrok http 3000

​
Step 6: Test with Sandbox

  1. Open your checkout page in the browser
  2. Use the test card 4242 4242 4242 4242 with any future expiry and any CVC
  3. Complete the purchase
  4. Verify the webhook fires in your terminal
When you are ready for production, update your environment variables:
  • Replace your sandbox access token with a production token
  • Change server: "sandbox" to server: "production" (or remove it entirely)
  • Update your webhook endpoint URL in the dashboard

​
What’s Next?

Webhook Events

See all available webhook event types

Customer Portal

Let customers manage their subscriptions

AI/LLM Billing

Bill customers based on AI model usage

Embedded Checkout

Advanced embedded checkout options