@proxy-checkout/stripe-server-js

Server-side Stripe adapter for Proxy Checkout. It owns the Stripe-specific integration protocol so merchant backends never hand-roll it:

• requiredMetadata(proxySession) — the proxy_session_id metadata Proxy needs on the Checkout Session, Subscription, and PaymentIntent.
• assertCheckoutSessionBelongsToProxy / assertSubscriptionBelongsToProxy / assertPaymentIntentBelongsToProxy — provider-object ownership checks.
• openCheckout(...) — records payer-opened, validates/reconciles the typed cart with rollback, injects required metadata, creates the Stripe Checkout Session with deterministic idempotency, records the Proxy provider binding, and returns the client secret. The merchant only supplies app-specific Stripe params.
• syncCheckoutCart(...) — validates the stored Proxy provider binding, then updates the Proxy cart and the Stripe Checkout line_items in the safest order with deterministic rollback/reconciliation (ProxyStripeCartSyncError).

PSP-agnostic primitives (sessions, subscriptions, webhooks, lifecycle) live in @proxy-checkout/server-js. This package is an additive adapter on top and is dependency-free: you inject your own Stripe instance and your @proxy-checkout/server-js client.

Install

npm install --save-exact @proxy-checkout/stripe-server-js @proxy-checkout/server-js stripe

Usage

import Stripe from "stripe";
import { createProxyCheckoutServerClient } from "@proxy-checkout/server-js";
import { openCheckout, syncCheckoutCart } from "@proxy-checkout/stripe-server-js";

const proxy = createProxyCheckoutServerClient({ apiKey: process.env.PROXY_SECRET_KEY! });
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: "2025-12-15.clover" });

// Create the merchant-owned Stripe checkout, correctly linked to the Proxy session.
const checkout = await openCheckout({
  proxy,
  stripe,
  proxySessionId,
  cartSchema, // a zod-style schema, or any (value) => Cart validator
  validateCart: ({ cart }) => buildMerchantOffer(cart),
  buildCheckoutSessionParams: ({ cart, offer }) => ({
    ...buildMerchantStripeParams(cart, offer),
    mode: "subscription",
    ui_mode: "custom",
  }),
});
// checkout.clientSecret -> render Stripe Elements

// Cart edits go through the binding-validated sync helper.
await syncCheckoutCart({
  proxy,
  stripe,
  proxySessionId,
  checkoutSessionId: checkout.checkoutSession.id,
  cartSchema,
  input: { interval: "year" },
  buildNextCart: ({ currentCart, input }) => buildMerchantCart(currentCart, input),
  buildStripeLineItems: (cart) => cart.lineItems,
});

Use the delegated-checkout guide from your Proxy onboarding materials for the full four-route integration recipe.