@proxy-checkout/server-js

Server-side JavaScript SDK for merchant backends calling Proxy merchant APIs.

Exposed API Endpoints

This package should expose the merchant-authenticated backend routes that exist today:

| SDK method | HTTP endpoint | Purpose | | --- | --- | --- | | proxy.sessions.create | POST /proxy_sessions | Create a Proxy Elements session. | | proxy.sessions.createHandoff | POST /proxy_sessions/handoff | Create a Proxy session and atomically mark it ready for hosted payer handoff. | | proxy.sessions.retrieve | GET /proxy_sessions/:id/merchant | Retrieve current merchant-owned session state after a webhook or before creating PSP objects. | | proxy.sessions.cart.set | PUT /proxy_sessions/:id/cart | Replace the current cart snapshot before payment orchestration. | | proxy.sessions.payerHandoff | POST /proxy_sessions/:id/payer_handoff | Low-level escape hatch. Most delegated checkout integrations should use createHandoff. | | proxy.sessions.payerOpened | POST /proxy_sessions/:id/payer_opened | Low-level escape hatch. Stripe integrations should usually let @proxy-checkout/stripe-server-js call this through openCheckout. | | proxy.subscriptions.retrieve | GET /subscriptions/:id | Retrieve current Proxy-linked subscription lifecycle state. | | proxy.liveContractDiagnostics.retrieve | GET /stripe_live_contract_diagnostics | Retrieve bounded, provider-ID-free evidence for a test-mode Stripe live-contract run, including per-session shared-planner shadow comparisons. | | proxy.webhookEndpoints.list | GET /webhook_endpoints | List outbound merchant webhook endpoints. | | proxy.webhookEndpoints.create | POST /webhook_endpoints | Create an outbound endpoint and receive its one-time signing secret. | | proxy.webhookEndpoints.get | GET /webhook_endpoints/:id | Read one outbound endpoint. | | proxy.webhookEndpoints.update | PATCH /webhook_endpoints/:id | Update URL, event types, or active/inactive status. | | proxy.webhookEndpoints.archive | POST /webhook_endpoints/:id/archive | Archive an outbound endpoint. | | proxy.webhookEndpoints.rotateSecret | POST /webhook_endpoints/:id/rotate_secret | Rotate an outbound endpoint signing secret. |

Usage

import { createProxyCheckoutServerClient } from "@proxy-checkout/server-js";

const proxy = createProxyCheckoutServerClient({
  apiKey: process.env.PROXY_SECRET_KEY!,
  publishableKey: process.env.PROXY_PUBLISHABLE_KEY!,
  payHost: process.env.PROXY_PAY_HOST,
});

const handoff = await proxy.sessions.createHandoff({
  amountMinor: 5000,
  // Stable, non-PII entitlement owner reference. For pre-account flows,
  // use a pending entitlement id instead of an email address.
  buyerReference: "buyer_123",
  // Optional beneficiary contact for the person receiving access.
  beneficiaryContact: { email: "[email protected]" },
  currency: "usd",
  cartSnapshot: {
    items: [{ product_id: "prod_123", quantity: 1 }],
  },
  // Stable merchant purchase-request id: reuse for retries and every payer
  // invited to this order; use a new id for a genuinely new purchase.
  idempotencyKey: "proxy-session:purchase_request_123",
  // Optional: omit in normal production flows to use the dashboard default.
  // Preview/staging/multi-origin environments may override the merchant payer page.
  payerDestinationUrl: "https://preview.example.com/checkout",
});

console.log(handoff.handoffUrl);

const currentSession = await proxy.sessions.retrieve(handoff.id);
console.log(currentSession.buyerReference);

const opened = await proxy.sessions.payerOpened(handoff.id);
console.log(opened.buyerReference, opened.cartSnapshot);

const endpoint = await proxy.webhookEndpoints.create({
  url: "https://example.com/proxy-webhooks",
  eventTypes: ["proxy_session.paid", "proxy_session.expired"],
});

console.log(endpoint.signingSecret);

For delegated checkout, prefer the high-level flow:

1. Create buyer handoffs with proxy.sessions.createHandoff(...).
2. Let @proxy-checkout/stripe-server-js openCheckout(...) record payer-opened, create the merchant-owned Stripe object, inject required metadata, and record provider binding.
3. Let proxy.webhooks.handle(...) verify signed Proxy webhooks, resolve current state, and acknowledge initial provisioning.

Use payerHandoff, payerOpened, raw event construction, or manual provisioning acknowledgements only for custom integrations that cannot use the default helpers.

The legacy proxy.sessions.recordProviderBinding(...) compatibility adapter is deprecated. If a custom Stripe integration still calls it directly, pass canonical psp: "stripe" plus commercialMode: "one_time" for Checkout mode: "payment" or commercialMode: "subscription" for Checkout mode: "subscription". Current TypeScript callers receive that requirement at compile time; openCheckout(...) derives it automatically.

proxy.webhooks.handle(...) automatically marks successful initial provisioning as provisioned after onResolved completes. Return a fulfillment reference and/or metadata from onResolved when you want that acknowledgement to record the merchant-side access row:

await proxy.webhooks.handle(request, {
  secret: process.env.PROXY_WEBHOOK_SIGNING_SECRET!,
  async onResolved(resolved) {
    if (resolved.kind !== "initial_provision") {
      return;
    }

    const entitlement = await grantOrMarkPending(resolved.session);
    return {
      fulfillmentReference: entitlement.id,
      metadata: { claim_status: entitlement.profileId ? "claimed" : "pending_account_claim" },
    };
  },
});

fulfillmentReference is copied to Proxy's proxy_session.provisioned session/audit event. Use it for support and reconciliation, for example "Proxy session psess_... was fulfilled by Fiveable pending entitlement pent_...." It does not grant access and is not used for future claim validation.

For pre-account purchases, create a durable pending entitlement before sessions.createHandoff(...), use that pending entitlement id as buyerReference, pass the future recipient's contact as beneficiaryContact, and claim the entitlement after signup/login with your own high-entropy claim token. Store only the token hash on the pending entitlement; use sessionStorage or an emailed merchant-owned claim link to carry the plaintext token to the authenticated claim endpoint. Treat proxy_session_id as public correlation, not as a claim secret.

Keep purchase identity separate from beneficiary identity. Create a durable merchant purchase-request/order row before createHandoff, derive idempotencyKey from that row's stable non-PII id, and store the returned Proxy session/handoff on it. Reuse the row and one handoff across HTTP retries and every invited payer. buyerReference identifies the entitlement recipient; it is not, by itself, an order key. A repeated purchase by the same beneficiary needs a new purchase-request id even if its offer and amount are unchanged. Do not derive the key from email, payer identity, Stripe Customer id, amount alone, or a per-retry random value.

One shared handoff supports simultaneous viewers. Opening never grants checkout ownership or a viewer lease. All authorized viewers can render the same cart/current state; identical provider preparation joins the same order-scoped acquisition, and a completed session remains readable while further provider creation is refused.

Verify and parse outbound webhooks with the exact raw request body:

import { constructProxyWebhookEvent } from "@proxy-checkout/server-js";

const event = constructProxyWebhookEvent({
  body: rawBodyBuffer,
  header: request.headers["proxy-signature"],
  secret: process.env.PROXY_WEBHOOK_SIGNING_SECRET!,
});

if (event.type === "subscription.renewed") {
  const subscription = await proxy.subscriptions.retrieve(event.data.subscription_id);
  console.log(subscription.currentPeriodEnd);
}

PROXY_WEBHOOK_EVENT_TYPES and the isProxy*Event predicates also cover initial payment refunds and observation-only Shopify reconciliation/renewal/refund/fulfillment events. Shopify observation events do not initiate a commerce mutation or imply provisioning; inspect their verified event.data payload.

Production calls default to https://api.proxycheckout.com. Tests, local development, and previews can pass apiHost.

Configure a production/default payer destination and allowed hosts in the Proxy dashboard. payerDestinationUrl is optional. Most production integrations can omit it and use the dashboard default. Preview, staging, or multi-origin environments may pass payerDestinationUrl to sessions.createHandoff(...); Proxy validates the host against the configured allowed hosts, stores the destination on the handoff session, and forwards the payer there when the hosted handoff opens.

First Publish Decisions

The first public package versions are intentionally 0.0.x because the SDK API is early and expected to change. The npm package is MIT-licensed under the package-scoped LICENSE file.

The package metadata is intentionally shaped for a public npm package, but the first publish still needs explicit owner approval for:

• release automation, provenance, dist tags, and rollback ownership.