Create checkout sessions in a Route Handler or server action. Return a narrow DTO containing the session ID, client token, and expiry; never serialize the merchant API key into a client component.

Route Handler

Client component

Load the SDK in a client component, mount after the server response, and destroy it on unmount. Set Cache-Control: no-store on token responses and do not put them in a permanent cache, URL, analytics event, or error message.

Webhooks

Handle signed events in a Route Handler that reads the raw body. Keep webhook fulfillment independent of the browser component and use a durable store for event IDs.
The complete maintained snippet is snippets/merchant-nextjs-route.ts in the repository. It keeps the API key server-side, returns X-Request-Id to the caller, and never treats a browser callback as fulfillment authority.