@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",
});

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.

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.