Integrating Overlay Checkout with Paddle.js

To accept payments, load the Paddle.js library. Paddle.js renders an Overlay Checkout directly over your page, giving users a smooth payment experience without redirects.

1. Initializing Paddle.js in React

Load the script using the CDN package or initialize it programmatically.

# Install the official Paddle client SDK helper
npm install @paddle/paddle-js

Initialize the checkout client inside a global layout helper or provider:

// src/lib/paddleClient.ts
import { initializePaddle, Paddle } from "@paddle/paddle-js";

let paddleInstance: Paddle | undefined;

export async function getPaddle() {
  if (!paddleInstance) {
    paddleInstance = await initializePaddle({
      environment: "sandbox", // Use "production" for live stores
      token: process.env.NEXT_PUBLIC_PADDLE_CLIENT_TOKEN as string,
    });
  }
  return paddleInstance;
}

2. Triggering the Overlay checkout popup

To open the checkout window, bind a click event that passes a target pricing configuration ID (priceId):

// app/pricing/PayButton.tsx
"use client";

import React from "react";
import { getPaddle } from "../../lib/paddleClient";

export default function PayButton({ priceId }: { priceId: string }) {
  async function handlePayment() {
    const paddle = await getPaddle();

    if (!paddle) return;

    // Trigger the overlay popup checkout
    paddle.Checkout.open({
      items: [
        {
          priceId: priceId, // e.g. "pri_01hsabc..."
          quantity: 1,
        },
      ],
      settings: {
        theme: "light",
        locale: "en",
        allowRecovery: true,
      },
    });
  }

  return (
    <button
      onClick={handlePayment}
      className="w-full bg-blue-600 hover:bg-blue-700 text-white font-semibold py-2.5 rounded-lg text-sm transition"
    >
      Upgrade Account
    </button>
  );
}