@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`	Record merchant handoff issuance before the payer loads checkout.
`proxy.sessions.payerOpened`	`POST /proxy_sessions/:id/payer_opened`	Record checkout open and read the current merchant session/cart state.
`proxy.subscriptions.retrieve`	`GET /subscriptions/:id`	Retrieve current Proxy-linked subscription lifecycle state.
`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,
  buyerReference: "buyer_123",
  currency: "usd",
  cartSnapshot: {
    items: [{ product_id: "prod_123", quantity: 1 }],
  },
  idempotencyKey: "order_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);

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);
}

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.