Integrate OurPay with Next.js

Consider following this guide while using the OurPay Sandbox Environment. This will allow you to test your integration without affecting your production data.

Install the OurPay JavaScript SDK

Install the official OurPay SDK:

Terminal

pnpm install @ourpay-dev/sdk@next

Setting up environment variables

OurPay Access Token

To authenticate with OurPay, you need to create an access token, and supply it to Next.js using a OURPAY_ACCESS_TOKEN environment variable. You can create an organization access token from your organization settings.

Configuring an OurPay API Client

To interact with the OurPay API, create a versioned client with the access token you generated.

// src/ourpay.ts
import { createOurPay } from "@ourpay-dev/sdk/2026-10";

export const api = createOurPay({
  accessToken: process.env.OURPAY_ACCESS_TOKEN!,
  environment: "sandbox",
});

Remember to replace sandbox with production when you’re ready to switch to the production environment.

Generating OurPay Checkout Sessions

Next up, we need to create a checkout endpoint to handle the creation of checkout sessions. Go ahead and create a new GET route in Next.js.

// src/app/checkout/route.ts
import { api } from "@/ourpay";

export async function GET(request: Request) {
  const productId = new URL(request.url).searchParams.get("product");
  if (!productId) {
    return Response.json({ error: "Missing product" }, { status: 400 });
  }

  const checkout = await api.checkouts.create({
    products: [productId],
    success_url: "https://your-app.com/confirmation?checkout_id={CHECKOUT_ID}",
  });

  return Response.redirect(checkout.url, 303);
}

Handling OurPay Webhooks

OurPay can send you events about various things happening in your organization. This is very useful for keeping your database in sync with OurPay checkouts, orders, subscriptions, etc. Configuring a webhook is simple. Head over to your organization’s settings page and click on the “Add Endpoint” button to create a new webhook.

Tunneling webhook events to your local development environment

If you’re developing locally, you can use a tool like ngrok to tunnel webhook events to your local development environment. This will allow you to test your webhook handlers without deploying them to a live server. Run the following command to start an ngrok tunnel:

Terminal

ngrok http 3000

Add Webhook Endpoint

Point the Webhook to your-app.com/api/webhook/ourpay. This must be an absolute URL which OurPay can reach. If you use ngrok, the URL will look something like this: https://<your-ngrok-id>.ngrok-free.app/api/webhook/ourpay.
Select which events you want to be notified about. You can read more about the available events in the Events section.
Generate a secret key to sign the requests. This will allow you to verify that the requests are truly coming from OurPay.
Add the secret key to your environment variables.

Terminal

# .env
OURPAY_ACCESS_TOKEN="ourpay_pat..."
OURPAY_WEBHOOK_SECRET="ourpay_whs_..."

Setting up the Webhook handler

// src/app/api/webhook/ourpay/route.ts
import { webhooks } from "@ourpay-dev/sdk/2026-10";

export async function POST(request: Request) {
  const secret = process.env.OURPAY_WEBHOOK_SECRET;
  if (!secret) {
    return Response.json({ error: "Webhook secret is not configured" }, { status: 500 });
  }

  try {
    const event = await webhooks.validateEvent(
      await request.text(),
      {
        "webhook-id": request.headers.get("webhook-id") ?? "",
        "webhook-timestamp": request.headers.get("webhook-timestamp") ?? "",
        "webhook-signature": request.headers.get("webhook-signature") ?? "",
      },
      secret,
    );

    if (event.type === "order.paid") {
      console.log("Paid order", event.data.id);
    }

    return Response.json({ received: true });
  } catch (error) {
    if (error instanceof webhooks.OurPayWebhookVerificationError) {
      return Response.json({ error: "Invalid signature" }, { status: 403 });
    }
    if (error instanceof webhooks.OurPayWebhookError) {
      return Response.json({ error: "Invalid payload" }, { status: 400 });
    }
    throw error;
  }
}

The handler verifies the raw request before branching on the typed event payload. Keep every handler idempotent because webhook deliveries can be retried.

Notifying the client about the event

If you’re building a real-time application, you might want to notify the client about the event. On the confirmation-page, you can listen for the checkout.updated event and update the UI accordingly when it reaches the succeeded status.

Bootup

Features

Integrate

Merchant of Record (MoR)

Integrate OurPay with Next.js

Install the OurPay JavaScript SDK

Setting up environment variables

OurPay Access Token

Configuring an OurPay API Client

Generating OurPay Checkout Sessions

Handling OurPay Webhooks

Tunneling webhook events to your local development environment

Add Webhook Endpoint

Setting up the Webhook handler

Notifying the client about the event

​Install the OurPay JavaScript SDK

​Setting up environment variables

​OurPay Access Token

​Configuring an OurPay API Client

​Generating OurPay Checkout Sessions

​Handling OurPay Webhooks

​Tunneling webhook events to your local development environment

​Add Webhook Endpoint

​Setting up the Webhook handler

​Notifying the client about the event

Install the OurPay JavaScript SDK

Setting up environment variables

OurPay Access Token

Configuring an OurPay API Client

Generating OurPay Checkout Sessions

Handling OurPay Webhooks

Tunneling webhook events to your local development environment

Add Webhook Endpoint

Setting up the Webhook handler

Notifying the client about the event