@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.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 cart details.
`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!,
});

const session = await proxy.sessions.create({
  amountMinor: 5000,
  buyerReference: "buyer_123",
  currency: "usd",
  cartSnapshot: {
    items: [{ product_id: "prod_123", quantity: 1 }],
  },
  idempotencyKey: "order_123",
});

await proxy.sessions.payerHandoff(session.id);

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

console.log(endpoint.signingSecret);

Verify outbound webhook signatures with the exact raw request body:

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

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

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

First Publish Decisions

The first public package version is intentionally 0.0.1 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.