@proxy-checkout/server-js 0.0.6 → 0.0.7

package/README.md

@@ -12,8 +12,8 @@ This package should expose the merchant-authenticated backend routes that exist
 | `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.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.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. |
@@ -62,6 +62,14 @@ const endpoint = await proxy.webhookEndpoints.create({
 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.
+
 Verify and parse outbound webhooks with the exact raw request body:
 
 ```ts

package/dist/cjs/errors.d.cts

@@ -29,4 +29,6 @@ export declare class ProxyCheckoutApiError extends Error {
     readonly statusCode: number;
     constructor(message: string, details: ProxyCheckoutApiErrorDetails);
 }
+export declare const PROXY_SESSION_NOT_FOUND_ERROR_CODE = "proxy_session_not_found";
+export declare function isProxySessionNotFoundError(error: unknown): error is ProxyCheckoutApiError;
 export declare function toApiError(statusCode: number, responseBody: unknown, headerRequestId?: string): ProxyCheckoutApiError;

package/dist/cjs/errors.d.ts

@@ -29,4 +29,6 @@ export declare class ProxyCheckoutApiError extends Error {
     readonly statusCode: number;
     constructor(message: string, details: ProxyCheckoutApiErrorDetails);
 }
+export declare const PROXY_SESSION_NOT_FOUND_ERROR_CODE = "proxy_session_not_found";
+export declare function isProxySessionNotFoundError(error: unknown): error is ProxyCheckoutApiError;
 export declare function toApiError(statusCode: number, responseBody: unknown, headerRequestId?: string): ProxyCheckoutApiError;

package/dist/cjs/errors.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProxyCheckoutApiError = exports.ProxyCheckoutValidationError = void 0;
+exports.PROXY_SESSION_NOT_FOUND_ERROR_CODE = exports.ProxyCheckoutApiError = exports.ProxyCheckoutValidationError = void 0;
+exports.isProxySessionNotFoundError = isProxySessionNotFoundError;
 exports.toApiError = toApiError;
 /**
  * Raised when the SDK receives Proxy data it cannot safely normalize, for
@@ -35,6 +36,22 @@ class ProxyCheckoutApiError extends Error {
     }
 }
 exports.ProxyCheckoutApiError = ProxyCheckoutApiError;
+exports.PROXY_SESSION_NOT_FOUND_ERROR_CODE = "proxy_session_not_found";
+function isProxySessionNotFoundError(error) {
+    if (error instanceof ProxyCheckoutApiError) {
+        return error.statusCode === 404 && error.code === exports.PROXY_SESSION_NOT_FOUND_ERROR_CODE;
+    }
+    // Preserve classification across ESM/CJS or bundled SDK boundaries where
+    // instanceof can fail even though the error still came from Proxy.
+    return (typeof error === "object" &&
+        error !== null &&
+        "name" in error &&
+        error.name === "ProxyCheckoutApiError" &&
+        "statusCode" in error &&
+        error.statusCode === 404 &&
+        "code" in error &&
+        error.code === exports.PROXY_SESSION_NOT_FOUND_ERROR_CODE);
+}
 function toApiError(statusCode, responseBody, headerRequestId) {
     const error = readApiError(responseBody);
     const message = error.message ?? `Proxy API request failed with status ${statusCode}.`;

package/dist/cjs/index.d.cts

@@ -1,7 +1,7 @@
 export { type ProxyCartParseOptions, type ProxyCartValidator, parseProxyCart, } from "./cart.js";
 export { createProxyCheckoutServerClient, ProxyCheckoutServerClient, } from "./client.js";
 export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./consistency.js";
-export { ProxyCheckoutApiError, type ProxyCheckoutApiErrorDetails, type ProxyCheckoutValidationCode, ProxyCheckoutValidationError, } from "./errors.js";
+export { isProxySessionNotFoundError, PROXY_SESSION_NOT_FOUND_ERROR_CODE, ProxyCheckoutApiError, type ProxyCheckoutApiErrorDetails, type ProxyCheckoutValidationCode, ProxyCheckoutValidationError, } from "./errors.js";
 export { ProxyEventsResource, type ResolvedIgnored, type ResolvedInitialProvision, type ResolvedPaymentAttempt, type ResolvedPaymentRisk, type ResolvedProxyEvent, type ResolvedProxyEventKind, type ResolvedSubscriptionCancelled, type ResolvedSubscriptionCancelScheduled, type ResolvedSubscriptionRenewed, type ResolvedTerminalSession, type ResolveProxyEventOptions, } from "./events.js";
 export { AT_RISK_SUBSCRIPTION_STATUSES, ENDED_SUBSCRIPTION_STATUSES, isSessionProvisionable, isSessionTerminal, isSubscriptionEnded, isSubscriptionPaymentAtRisk, PROVISIONABLE_SESSION_STATUSES, parseOptionalProxyDate, requireProxyDate, subscriptionAccessEndsAt, subscriptionWillRenew, TERMINAL_SESSION_STATUSES, } from "./lifecycle.js";
 export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MarkProxySessionProvisionedInput, type MarkProxySessionProvisioningFailedInput, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionProviderBinding, type ProxySessionProvisioningAcknowledgement, ProxySessionsResource, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.js";

package/dist/cjs/index.d.ts

@@ -1,7 +1,7 @@
 export { type ProxyCartParseOptions, type ProxyCartValidator, parseProxyCart, } from "./cart.js";
 export { createProxyCheckoutServerClient, ProxyCheckoutServerClient, } from "./client.js";
 export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./consistency.js";
-export { ProxyCheckoutApiError, type ProxyCheckoutApiErrorDetails, type ProxyCheckoutValidationCode, ProxyCheckoutValidationError, } from "./errors.js";
+export { isProxySessionNotFoundError, PROXY_SESSION_NOT_FOUND_ERROR_CODE, ProxyCheckoutApiError, type ProxyCheckoutApiErrorDetails, type ProxyCheckoutValidationCode, ProxyCheckoutValidationError, } from "./errors.js";
 export { ProxyEventsResource, type ResolvedIgnored, type ResolvedInitialProvision, type ResolvedPaymentAttempt, type ResolvedPaymentRisk, type ResolvedProxyEvent, type ResolvedProxyEventKind, type ResolvedSubscriptionCancelled, type ResolvedSubscriptionCancelScheduled, type ResolvedSubscriptionRenewed, type ResolvedTerminalSession, type ResolveProxyEventOptions, } from "./events.js";
 export { AT_RISK_SUBSCRIPTION_STATUSES, ENDED_SUBSCRIPTION_STATUSES, isSessionProvisionable, isSessionTerminal, isSubscriptionEnded, isSubscriptionPaymentAtRisk, PROVISIONABLE_SESSION_STATUSES, parseOptionalProxyDate, requireProxyDate, subscriptionAccessEndsAt, subscriptionWillRenew, TERMINAL_SESSION_STATUSES, } from "./lifecycle.js";
 export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MarkProxySessionProvisionedInput, type MarkProxySessionProvisioningFailedInput, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionProviderBinding, type ProxySessionProvisioningAcknowledgement, ProxySessionsResource, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.js";

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.verifyProxyWebhookSignature = exports.proxyCheckoutWebhookEndpointEndpoints = exports.ProxyWebhookSignatureVerificationError = exports.ProxyWebhookEndpointsResource = exports.PROXY_SIGNATURE_HEADER = exports.constructProxyWebhookEvent = exports.ProxyWebhooksResource = exports.PROXY_WEBHOOK_RETRY_AFTER_SECONDS = exports.PROXY_WEBHOOK_EVENT_TYPES = exports.isProxySubscriptionEvent = exports.isProxySessionEvent = exports.isProxyPaymentAttemptEvent = exports.proxyCheckoutServerSdkVersion = exports.proxyCheckoutServerSdkUserAgent = exports.proxyCheckoutServerSdkName = exports.proxyCheckoutSubscriptionEndpoints = exports.ProxySubscriptionsResource = exports.proxyCheckoutServerEndpoints = exports.ProxySessionsResource = exports.ProxySessionCartResource = exports.TERMINAL_SESSION_STATUSES = exports.subscriptionWillRenew = exports.subscriptionAccessEndsAt = exports.requireProxyDate = exports.parseOptionalProxyDate = exports.PROVISIONABLE_SESSION_STATUSES = exports.isSubscriptionPaymentAtRisk = exports.isSubscriptionEnded = exports.isSessionTerminal = exports.isSessionProvisionable = exports.ENDED_SUBSCRIPTION_STATUSES = exports.AT_RISK_SUBSCRIPTION_STATUSES = exports.ProxyEventsResource = exports.ProxyCheckoutValidationError = exports.ProxyCheckoutApiError = exports.assertSubscriptionMatchesSession = exports.assertCartBuyerReference = exports.ProxyCheckoutServerClient = exports.createProxyCheckoutServerClient = exports.parseProxyCart = void 0;
+exports.verifyProxyWebhookSignature = exports.proxyCheckoutWebhookEndpointEndpoints = exports.ProxyWebhookSignatureVerificationError = exports.ProxyWebhookEndpointsResource = exports.PROXY_SIGNATURE_HEADER = exports.constructProxyWebhookEvent = exports.ProxyWebhooksResource = exports.PROXY_WEBHOOK_RETRY_AFTER_SECONDS = exports.PROXY_WEBHOOK_EVENT_TYPES = exports.isProxySubscriptionEvent = exports.isProxySessionEvent = exports.isProxyPaymentAttemptEvent = exports.proxyCheckoutServerSdkVersion = exports.proxyCheckoutServerSdkUserAgent = exports.proxyCheckoutServerSdkName = exports.proxyCheckoutSubscriptionEndpoints = exports.ProxySubscriptionsResource = exports.proxyCheckoutServerEndpoints = exports.ProxySessionsResource = exports.ProxySessionCartResource = exports.TERMINAL_SESSION_STATUSES = exports.subscriptionWillRenew = exports.subscriptionAccessEndsAt = exports.requireProxyDate = exports.parseOptionalProxyDate = exports.PROVISIONABLE_SESSION_STATUSES = exports.isSubscriptionPaymentAtRisk = exports.isSubscriptionEnded = exports.isSessionTerminal = exports.isSessionProvisionable = exports.ENDED_SUBSCRIPTION_STATUSES = exports.AT_RISK_SUBSCRIPTION_STATUSES = exports.ProxyEventsResource = exports.ProxyCheckoutValidationError = exports.ProxyCheckoutApiError = exports.PROXY_SESSION_NOT_FOUND_ERROR_CODE = exports.isProxySessionNotFoundError = exports.assertSubscriptionMatchesSession = exports.assertCartBuyerReference = exports.ProxyCheckoutServerClient = exports.createProxyCheckoutServerClient = exports.parseProxyCart = void 0;
 var cart_js_1 = require("./cart.js");
 Object.defineProperty(exports, "parseProxyCart", { enumerable: true, get: function () { return cart_js_1.parseProxyCart; } });
 var client_js_1 = require("./client.js");
@@ -10,6 +10,8 @@ var consistency_js_1 = require("./consistency.js");
 Object.defineProperty(exports, "assertCartBuyerReference", { enumerable: true, get: function () { return consistency_js_1.assertCartBuyerReference; } });
 Object.defineProperty(exports, "assertSubscriptionMatchesSession", { enumerable: true, get: function () { return consistency_js_1.assertSubscriptionMatchesSession; } });
 var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "isProxySessionNotFoundError", { enumerable: true, get: function () { return errors_js_1.isProxySessionNotFoundError; } });
+Object.defineProperty(exports, "PROXY_SESSION_NOT_FOUND_ERROR_CODE", { enumerable: true, get: function () { return errors_js_1.PROXY_SESSION_NOT_FOUND_ERROR_CODE; } });
 Object.defineProperty(exports, "ProxyCheckoutApiError", { enumerable: true, get: function () { return errors_js_1.ProxyCheckoutApiError; } });
 Object.defineProperty(exports, "ProxyCheckoutValidationError", { enumerable: true, get: function () { return errors_js_1.ProxyCheckoutValidationError; } });
 var events_js_1 = require("./events.js");

package/dist/cjs/sessions.js

@@ -73,9 +73,6 @@ class ProxySessionsResource {
             throw new Error("Proxy Checkout sessions.createHandoff requires a publishableKey option or input field.");
         }
         const payHost = input.payHost ?? this.options.payHost;
-        if (!payHost && this.httpClient.apiHost !== "https://api.proxycheckout.com") {
-            throw new Error("Proxy Checkout sessions.createHandoff requires a payHost option or input field when apiHost is overridden.");
-        }
         const response = await this.httpClient.request("POST", "/proxy_sessions/handoff", {
             ...toCreateProxySessionBody(input),
             ...(input.payerDestinationUrl !== undefined
@@ -87,13 +84,19 @@ class ProxySessionsResource {
             requestId: input.requestId,
         });
         const session = toProxySessionHandoff(response);
+        if (!session.handoffUrl &&
+            !payHost &&
+            this.httpClient.apiHost !== "https://api.proxycheckout.com") {
+            throw new Error("Proxy Checkout sessions.createHandoff requires a payHost option or input field when apiHost is overridden and the API response does not include handoff_url.");
+        }
         return {
             ...session,
-            handoffUrl: buildHandoffUrl({
-                payHost,
-                proxySessionId: session.id,
-                publishableKey,
-            }),
+            handoffUrl: session.handoffUrl ||
+                buildHandoffUrl({
+                    payHost,
+                    proxySessionId: session.id,
+                    publishableKey,
+                }),
         };
     }
     async retrieve(proxySessionId, options = {}) {
@@ -239,7 +242,11 @@ function toProxySessionHandoff(response) {
     const integrationMode = (0, response_validators_js_1.requireString)(body.integration_mode, "sessions.createHandoff.integrationMode");
     return {
         expiresAt: (0, response_validators_js_1.requireString)(body.expires_at, "sessions.createHandoff.expiresAt"),
-        handoffUrl: "",
+        handoffUrl: typeof body.handoff_url === "string"
+            ? body.handoff_url
+            : typeof body.handoffUrl === "string"
+                ? body.handoffUrl
+                : "",
         id: (0, response_validators_js_1.requireString)(body.id, "sessions.createHandoff.id"),
         integrationMode,
         status,

package/dist/cjs/version.d.cts

@@ -1,3 +1,3 @@
 export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export declare const proxyCheckoutServerSdkVersion = "0.0.6";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.6";
+export declare const proxyCheckoutServerSdkVersion = "0.0.7";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.7";

package/dist/cjs/version.d.ts

@@ -1,3 +1,3 @@
 export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export declare const proxyCheckoutServerSdkVersion = "0.0.6";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.6";
+export declare const proxyCheckoutServerSdkVersion = "0.0.7";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.7";

package/dist/cjs/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.proxyCheckoutServerSdkUserAgent = exports.proxyCheckoutServerSdkVersion = exports.proxyCheckoutServerSdkName = void 0;
 exports.proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-exports.proxyCheckoutServerSdkVersion = "0.0.6";
+exports.proxyCheckoutServerSdkVersion = "0.0.7";
 exports.proxyCheckoutServerSdkUserAgent = `${exports.proxyCheckoutServerSdkName}/${exports.proxyCheckoutServerSdkVersion}`;

package/dist/esm/errors.d.ts

@@ -29,4 +29,6 @@ export declare class ProxyCheckoutApiError extends Error {
     readonly statusCode: number;
     constructor(message: string, details: ProxyCheckoutApiErrorDetails);
 }
+export declare const PROXY_SESSION_NOT_FOUND_ERROR_CODE = "proxy_session_not_found";
+export declare function isProxySessionNotFoundError(error: unknown): error is ProxyCheckoutApiError;
 export declare function toApiError(statusCode: number, responseBody: unknown, headerRequestId?: string): ProxyCheckoutApiError;

package/dist/esm/errors.js

@@ -29,6 +29,22 @@ export class ProxyCheckoutApiError extends Error {
         this.statusCode = details.statusCode;
     }
 }
+export const PROXY_SESSION_NOT_FOUND_ERROR_CODE = "proxy_session_not_found";
+export function isProxySessionNotFoundError(error) {
+    if (error instanceof ProxyCheckoutApiError) {
+        return error.statusCode === 404 && error.code === PROXY_SESSION_NOT_FOUND_ERROR_CODE;
+    }
+    // Preserve classification across ESM/CJS or bundled SDK boundaries where
+    // instanceof can fail even though the error still came from Proxy.
+    return (typeof error === "object" &&
+        error !== null &&
+        "name" in error &&
+        error.name === "ProxyCheckoutApiError" &&
+        "statusCode" in error &&
+        error.statusCode === 404 &&
+        "code" in error &&
+        error.code === PROXY_SESSION_NOT_FOUND_ERROR_CODE);
+}
 export function toApiError(statusCode, responseBody, headerRequestId) {
     const error = readApiError(responseBody);
     const message = error.message ?? `Proxy API request failed with status ${statusCode}.`;

package/dist/esm/index.d.ts

@@ -1,7 +1,7 @@
 export { type ProxyCartParseOptions, type ProxyCartValidator, parseProxyCart, } from "./cart.js";
 export { createProxyCheckoutServerClient, ProxyCheckoutServerClient, } from "./client.js";
 export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./consistency.js";
-export { ProxyCheckoutApiError, type ProxyCheckoutApiErrorDetails, type ProxyCheckoutValidationCode, ProxyCheckoutValidationError, } from "./errors.js";
+export { isProxySessionNotFoundError, PROXY_SESSION_NOT_FOUND_ERROR_CODE, ProxyCheckoutApiError, type ProxyCheckoutApiErrorDetails, type ProxyCheckoutValidationCode, ProxyCheckoutValidationError, } from "./errors.js";
 export { ProxyEventsResource, type ResolvedIgnored, type ResolvedInitialProvision, type ResolvedPaymentAttempt, type ResolvedPaymentRisk, type ResolvedProxyEvent, type ResolvedProxyEventKind, type ResolvedSubscriptionCancelled, type ResolvedSubscriptionCancelScheduled, type ResolvedSubscriptionRenewed, type ResolvedTerminalSession, type ResolveProxyEventOptions, } from "./events.js";
 export { AT_RISK_SUBSCRIPTION_STATUSES, ENDED_SUBSCRIPTION_STATUSES, isSessionProvisionable, isSessionTerminal, isSubscriptionEnded, isSubscriptionPaymentAtRisk, PROVISIONABLE_SESSION_STATUSES, parseOptionalProxyDate, requireProxyDate, subscriptionAccessEndsAt, subscriptionWillRenew, TERMINAL_SESSION_STATUSES, } from "./lifecycle.js";
 export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MarkProxySessionProvisionedInput, type MarkProxySessionProvisioningFailedInput, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionProviderBinding, type ProxySessionProvisioningAcknowledgement, ProxySessionsResource, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.js";

package/dist/esm/index.js

@@ -1,7 +1,7 @@
 export { parseProxyCart, } from "./cart.js";
 export { createProxyCheckoutServerClient, ProxyCheckoutServerClient, } from "./client.js";
 export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./consistency.js";
-export { ProxyCheckoutApiError, ProxyCheckoutValidationError, } from "./errors.js";
+export { isProxySessionNotFoundError, PROXY_SESSION_NOT_FOUND_ERROR_CODE, ProxyCheckoutApiError, ProxyCheckoutValidationError, } from "./errors.js";
 export { ProxyEventsResource, } from "./events.js";
 export { AT_RISK_SUBSCRIPTION_STATUSES, ENDED_SUBSCRIPTION_STATUSES, isSessionProvisionable, isSessionTerminal, isSubscriptionEnded, isSubscriptionPaymentAtRisk, PROVISIONABLE_SESSION_STATUSES, parseOptionalProxyDate, requireProxyDate, subscriptionAccessEndsAt, subscriptionWillRenew, TERMINAL_SESSION_STATUSES, } from "./lifecycle.js";
 export { ProxySessionCartResource, ProxySessionsResource, proxyCheckoutServerEndpoints, } from "./sessions.js";

package/dist/esm/sessions.js

@@ -70,9 +70,6 @@ export class ProxySessionsResource {
             throw new Error("Proxy Checkout sessions.createHandoff requires a publishableKey option or input field.");
         }
         const payHost = input.payHost ?? this.options.payHost;
-        if (!payHost && this.httpClient.apiHost !== "https://api.proxycheckout.com") {
-            throw new Error("Proxy Checkout sessions.createHandoff requires a payHost option or input field when apiHost is overridden.");
-        }
         const response = await this.httpClient.request("POST", "/proxy_sessions/handoff", {
             ...toCreateProxySessionBody(input),
             ...(input.payerDestinationUrl !== undefined
@@ -84,13 +81,19 @@ export class ProxySessionsResource {
             requestId: input.requestId,
         });
         const session = toProxySessionHandoff(response);
+        if (!session.handoffUrl &&
+            !payHost &&
+            this.httpClient.apiHost !== "https://api.proxycheckout.com") {
+            throw new Error("Proxy Checkout sessions.createHandoff requires a payHost option or input field when apiHost is overridden and the API response does not include handoff_url.");
+        }
         return {
             ...session,
-            handoffUrl: buildHandoffUrl({
-                payHost,
-                proxySessionId: session.id,
-                publishableKey,
-            }),
+            handoffUrl: session.handoffUrl ||
+                buildHandoffUrl({
+                    payHost,
+                    proxySessionId: session.id,
+                    publishableKey,
+                }),
         };
     }
     async retrieve(proxySessionId, options = {}) {
@@ -234,7 +237,11 @@ function toProxySessionHandoff(response) {
     const integrationMode = requireString(body.integration_mode, "sessions.createHandoff.integrationMode");
     return {
         expiresAt: requireString(body.expires_at, "sessions.createHandoff.expiresAt"),
-        handoffUrl: "",
+        handoffUrl: typeof body.handoff_url === "string"
+            ? body.handoff_url
+            : typeof body.handoffUrl === "string"
+                ? body.handoffUrl
+                : "",
         id: requireString(body.id, "sessions.createHandoff.id"),
         integrationMode,
         status,

package/dist/esm/version.d.ts

@@ -1,3 +1,3 @@
 export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export declare const proxyCheckoutServerSdkVersion = "0.0.6";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.6";
+export declare const proxyCheckoutServerSdkVersion = "0.0.7";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.7";

package/dist/esm/version.js

@@ -1,3 +1,3 @@
 export const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export const proxyCheckoutServerSdkVersion = "0.0.6";
+export const proxyCheckoutServerSdkVersion = "0.0.7";
 export const proxyCheckoutServerSdkUserAgent = `${proxyCheckoutServerSdkName}/${proxyCheckoutServerSdkVersion}`;

package/package.json

@@ -7,7 +7,7 @@
   "sideEffects": false,
   "type": "module",
   "types": "./dist/esm/index.d.ts",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "devDependencies": {
     "@types/node": "^24.12.4",
     "@vitest/coverage-v8": "4.1.7",
@@ -48,6 +48,7 @@
   "scripts": {
     "build": "node ../../scripts/sdk/build-dual-package.mjs",
     "test:all": "vitest run",
+    "test:ci": "pnpm run test:coverage",
     "test:coverage": "vitest run --coverage.enabled --coverage.reportsDirectory=coverage/all",
     "test:coverage:changed": "vitest run --coverage.enabled --coverage.reportsDirectory=coverage/changed",
     "test:coverage:integration": "vitest run --project integration --coverage.enabled --coverage.reportsDirectory=coverage/integration",