@proxy-checkout/server-js 0.0.8-prx-120.97.1 → 0.0.8-prx-124.117.1

package/README.md

@@ -44,7 +44,9 @@ const handoff = await proxy.sessions.createHandoff({
   cartSnapshot: {
     items: [{ product_id: "prod_123", quantity: 1 }],
   },
-  idempotencyKey: "order_123",
+  // 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",
@@ -97,6 +99,10 @@ await proxy.webhooks.handle(request, {
 
 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:
 
 ```ts

package/dist/cjs/client.d.cts

@@ -1,4 +1,5 @@
 import { ProxyEventsResource } from "./events.js";
+import { ProxyProviderAcquisitionsResource } from "./provider-acquisitions.js";
 import { ProxySessionsResource } from "./sessions.js";
 import { ProxySubscriptionsResource } from "./subscriptions.js";
 import type { ProxyCheckoutServerClientOptions } from "./types.js";
@@ -7,6 +8,7 @@ import { ProxyWebhookEndpointsResource } from "./webhooks.js";
 export declare class ProxyCheckoutServerClient {
     readonly apiHost: string;
     readonly sessions: ProxySessionsResource;
+    readonly providerAcquisitions: ProxyProviderAcquisitionsResource;
     readonly subscriptions: ProxySubscriptionsResource;
     /** Current-state lifecycle resolver for signed webhook events. */
     readonly events: ProxyEventsResource;

package/dist/cjs/client.d.ts

@@ -1,4 +1,5 @@
 import { ProxyEventsResource } from "./events.js";
+import { ProxyProviderAcquisitionsResource } from "./provider-acquisitions.js";
 import { ProxySessionsResource } from "./sessions.js";
 import { ProxySubscriptionsResource } from "./subscriptions.js";
 import type { ProxyCheckoutServerClientOptions } from "./types.js";
@@ -7,6 +8,7 @@ import { ProxyWebhookEndpointsResource } from "./webhooks.js";
 export declare class ProxyCheckoutServerClient {
     readonly apiHost: string;
     readonly sessions: ProxySessionsResource;
+    readonly providerAcquisitions: ProxyProviderAcquisitionsResource;
     readonly subscriptions: ProxySubscriptionsResource;
     /** Current-state lifecycle resolver for signed webhook events. */
     readonly events: ProxyEventsResource;

package/dist/cjs/client.js

@@ -4,6 +4,7 @@ exports.ProxyCheckoutServerClient = void 0;
 exports.createProxyCheckoutServerClient = createProxyCheckoutServerClient;
 const events_js_1 = require("./events.js");
 const http_client_js_1 = require("./http-client.js");
+const provider_acquisitions_js_1 = require("./provider-acquisitions.js");
 const sessions_js_1 = require("./sessions.js");
 const subscriptions_js_1 = require("./subscriptions.js");
 const webhook_handler_js_1 = require("./webhook-handler.js");
@@ -11,6 +12,7 @@ const webhooks_js_1 = require("./webhooks.js");
 class ProxyCheckoutServerClient {
     apiHost;
     sessions;
+    providerAcquisitions;
     subscriptions;
     /** Current-state lifecycle resolver for signed webhook events. */
     events;
@@ -29,6 +31,7 @@ class ProxyCheckoutServerClient {
             payHost: options.payHost,
             publishableKey: options.publishableKey,
         });
+        this.providerAcquisitions = new provider_acquisitions_js_1.ProxyProviderAcquisitionsResource(httpClient);
         this.subscriptions = new subscriptions_js_1.ProxySubscriptionsResource(httpClient, this.sessions);
         this.events = new events_js_1.ProxyEventsResource(this.sessions, this.subscriptions);
         this.webhooks = new webhook_handler_js_1.ProxyWebhooksResource(this.events, this.sessions);

package/dist/cjs/errors.d.cts

@@ -4,7 +4,7 @@ export interface ProxyCheckoutApiErrorDetails {
     readonly responseBody: unknown;
     readonly statusCode: number;
 }
-export type ProxyCheckoutValidationCode = "buyer_reference_mismatch" | "cart_invalid" | "invalid_date" | "provider_binding_mismatch" | "subscription_session_mismatch" | "webhook_sessions_resource_missing";
+export type ProxyCheckoutValidationCode = "buyer_reference_mismatch" | "cart_invalid" | "invalid_date" | "invalid_session_presentation" | "provider_binding_missing" | "provider_binding_mismatch" | "subscription_session_mismatch" | "unsupported_provider_option" | "webhook_sessions_resource_missing";
 /**
  * Raised when the SDK receives Proxy data it cannot safely normalize, for
  * example an invalid date string, a cart snapshot that fails the merchant

package/dist/cjs/errors.d.ts

@@ -4,7 +4,7 @@ export interface ProxyCheckoutApiErrorDetails {
     readonly responseBody: unknown;
     readonly statusCode: number;
 }
-export type ProxyCheckoutValidationCode = "buyer_reference_mismatch" | "cart_invalid" | "invalid_date" | "provider_binding_mismatch" | "subscription_session_mismatch" | "webhook_sessions_resource_missing";
+export type ProxyCheckoutValidationCode = "buyer_reference_mismatch" | "cart_invalid" | "invalid_date" | "invalid_session_presentation" | "provider_binding_missing" | "provider_binding_mismatch" | "subscription_session_mismatch" | "unsupported_provider_option" | "webhook_sessions_resource_missing";
 /**
  * Raised when the SDK receives Proxy data it cannot safely normalize, for
  * example an invalid date string, a cart snapshot that fails the merchant

package/dist/cjs/index.d.cts

@@ -4,7 +4,8 @@ export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./c
 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";
+export { type AttachProviderAcquisitionObjectInput, type ProviderAcquisition, type ProviderAcquisitionCheckoutUiMode, type ProviderAcquisitionCommercialMode, type ProviderAcquisitionIntegrationPath, type ProviderAcquisitionObjectType, type ProviderAcquisitionPricingMode, type ProviderAcquisitionReservation, ProxyProviderAcquisitionsResource, proxyCheckoutProviderAcquisitionEndpoints, type ReserveProviderAcquisitionInput, type SupersedeProviderAcquisitionInput, } from "./provider-acquisitions.js";
+export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MarkProxySessionProvisionedInput, type MarkProxySessionProvisioningFailedInput, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, type ProxySessionAcquisitionSummary, type ProxySessionActionableNextStep, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionPresentationState, type ProxySessionProviderBinding, type ProxySessionProvisioningAcknowledgement, ProxySessionsResource, type ProxySessionViewStatus, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.js";
 export { type MerchantProxySubscription, ProxySubscriptionsResource, type ProxySubscriptionWithSession, type ProxySubscriptionWithUntypedSession, proxyCheckoutSubscriptionEndpoints, } from "./subscriptions.js";
 export type { JsonObject, JsonPrimitive, JsonValue, ProxyCheckoutFetch, ProxyCheckoutServerClientOptions, ProxyCheckoutServerRequestOptions, } from "./types.js";
 export { proxyCheckoutServerSdkName, proxyCheckoutServerSdkUserAgent, proxyCheckoutServerSdkVersion, } from "./version.js";

package/dist/cjs/index.d.ts

@@ -4,7 +4,8 @@ export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./c
 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";
+export { type AttachProviderAcquisitionObjectInput, type ProviderAcquisition, type ProviderAcquisitionCheckoutUiMode, type ProviderAcquisitionCommercialMode, type ProviderAcquisitionIntegrationPath, type ProviderAcquisitionObjectType, type ProviderAcquisitionPricingMode, type ProviderAcquisitionReservation, ProxyProviderAcquisitionsResource, proxyCheckoutProviderAcquisitionEndpoints, type ReserveProviderAcquisitionInput, type SupersedeProviderAcquisitionInput, } from "./provider-acquisitions.js";
+export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MarkProxySessionProvisionedInput, type MarkProxySessionProvisioningFailedInput, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, type ProxySessionAcquisitionSummary, type ProxySessionActionableNextStep, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionPresentationState, type ProxySessionProviderBinding, type ProxySessionProvisioningAcknowledgement, ProxySessionsResource, type ProxySessionViewStatus, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.js";
 export { type MerchantProxySubscription, ProxySubscriptionsResource, type ProxySubscriptionWithSession, type ProxySubscriptionWithUntypedSession, proxyCheckoutSubscriptionEndpoints, } from "./subscriptions.js";
 export type { JsonObject, JsonPrimitive, JsonValue, ProxyCheckoutFetch, ProxyCheckoutServerClientOptions, ProxyCheckoutServerRequestOptions, } from "./types.js";
 export { proxyCheckoutServerSdkName, proxyCheckoutServerSdkUserAgent, proxyCheckoutServerSdkVersion, } from "./version.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.isProxyShopifyEvent = 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;
+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.isProxyShopifyEvent = exports.isProxySessionEvent = exports.isProxyPaymentAttemptEvent = exports.proxyCheckoutServerSdkVersion = exports.proxyCheckoutServerSdkUserAgent = exports.proxyCheckoutServerSdkName = exports.proxyCheckoutSubscriptionEndpoints = exports.ProxySubscriptionsResource = exports.proxyCheckoutServerEndpoints = exports.ProxySessionsResource = exports.ProxySessionCartResource = exports.proxyCheckoutProviderAcquisitionEndpoints = exports.ProxyProviderAcquisitionsResource = 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");
@@ -29,6 +29,9 @@ Object.defineProperty(exports, "requireProxyDate", { enumerable: true, get: func
 Object.defineProperty(exports, "subscriptionAccessEndsAt", { enumerable: true, get: function () { return lifecycle_js_1.subscriptionAccessEndsAt; } });
 Object.defineProperty(exports, "subscriptionWillRenew", { enumerable: true, get: function () { return lifecycle_js_1.subscriptionWillRenew; } });
 Object.defineProperty(exports, "TERMINAL_SESSION_STATUSES", { enumerable: true, get: function () { return lifecycle_js_1.TERMINAL_SESSION_STATUSES; } });
+var provider_acquisitions_js_1 = require("./provider-acquisitions.js");
+Object.defineProperty(exports, "ProxyProviderAcquisitionsResource", { enumerable: true, get: function () { return provider_acquisitions_js_1.ProxyProviderAcquisitionsResource; } });
+Object.defineProperty(exports, "proxyCheckoutProviderAcquisitionEndpoints", { enumerable: true, get: function () { return provider_acquisitions_js_1.proxyCheckoutProviderAcquisitionEndpoints; } });
 var sessions_js_1 = require("./sessions.js");
 Object.defineProperty(exports, "ProxySessionCartResource", { enumerable: true, get: function () { return sessions_js_1.ProxySessionCartResource; } });
 Object.defineProperty(exports, "ProxySessionsResource", { enumerable: true, get: function () { return sessions_js_1.ProxySessionsResource; } });

package/dist/cjs/provider-acquisitions.d.cts

@@ -0,0 +1,98 @@
+import type { ProxyCheckoutHttpClient } from "./http-client.js";
+import type { ProxyCheckoutServerRequestOptions } from "./types.js";
+export type ProviderAcquisitionCommercialMode = "one_time" | "subscription";
+export type ProviderAcquisitionIntegrationPath = "checkout_session" | "direct_subscription" | "payment_intent";
+export type ProviderAcquisitionCheckoutUiMode = "custom" | "embedded" | "hosted";
+export type ProviderAcquisitionPricingMode = "fixed" | "provider_finalized";
+export type ProviderAcquisitionObjectType = "checkout_session" | "payment_intent" | "setup_intent" | "subscription";
+export interface ProviderAcquisition {
+    readonly attemptNumber: number;
+    readonly checkoutUiMode: ProviderAcquisitionCheckoutUiMode | "unknown" | null;
+    readonly commercialMode: ProviderAcquisitionCommercialMode;
+    readonly completionRecordedAt: string | null;
+    readonly createdAt: string;
+    readonly directFeeBasisSource: string | null;
+    readonly directMerchandiseCurrency: string | null;
+    readonly directMerchandiseSubtotalMinor: number | null;
+    readonly id: string;
+    readonly integrationPath: ProviderAcquisitionIntegrationPath;
+    readonly merchantPspConfigId: string;
+    readonly pricingMode: ProviderAcquisitionPricingMode;
+    readonly providerCreatedAt: string | null;
+    /** Stripe Customer ID retained only as a merchant-authenticated diagnostic. */
+    readonly providerCustomerId: string | null;
+    readonly providerRetryNotAfter: string;
+    readonly providerRootObjectId: string | null;
+    readonly providerRootObjectType: ProviderAcquisitionObjectType | null;
+    readonly providerSetupIntentId: string | null;
+    readonly proxySessionId: string;
+    readonly psp: "stripe";
+    readonly status: string;
+    readonly statusReason: string | null;
+    readonly supersedesAttemptId: string | null;
+    readonly updatedAt: string;
+    readonly version: number;
+}
+export interface ProviderAcquisitionReservation {
+    readonly acquisitionAttempt: ProviderAcquisition;
+    readonly stripe: {
+        readonly idempotencyKeys: {
+            readonly root: string;
+            readonly setupIntent?: string;
+        };
+        readonly metadata: {
+            readonly proxyAcquisitionAttemptId: string;
+            readonly proxyContractVersion: "2";
+            readonly proxySessionId: string;
+        };
+    };
+}
+export interface ReserveProviderAcquisitionInput extends ProxyCheckoutServerRequestOptions {
+    readonly checkoutUiMode?: ProviderAcquisitionCheckoutUiMode;
+    readonly commercialMode: ProviderAcquisitionCommercialMode;
+    readonly integrationPath: ProviderAcquisitionIntegrationPath;
+    /** Optional server-only direct PaymentIntent percentage basis; omit to use verified provider gross. */
+    readonly merchandiseSubtotalMinor?: number;
+    readonly pricingMode: ProviderAcquisitionPricingMode;
+    readonly providerOptionsFingerprint: string;
+}
+export interface AttachProviderAcquisitionObjectInput extends ProxyCheckoutServerRequestOptions {
+    readonly expectedVersion: number;
+    readonly objectId: string;
+    readonly objectType: ProviderAcquisitionObjectType;
+    readonly role: "root" | "setup_intent";
+}
+export interface SupersedeProviderAcquisitionInput extends ProxyCheckoutServerRequestOptions {
+    readonly expectedVersion: number;
+    readonly reason: string;
+    readonly replacement: {
+        readonly checkoutUiMode?: ProviderAcquisitionCheckoutUiMode;
+        readonly integrationPath: ProviderAcquisitionIntegrationPath;
+        readonly providerOptionsFingerprint: string;
+    };
+}
+export declare const proxyCheckoutProviderAcquisitionEndpoints: readonly [{
+    readonly method: "POST";
+    readonly operation: "providerAcquisitions.reserveProviderAcquisition";
+    readonly path: "/proxy_sessions/:proxy_session_id/acquisition_attempts";
+}, {
+    readonly method: "POST";
+    readonly operation: "providerAcquisitions.attachProviderAcquisitionObject";
+    readonly path: "/proxy_sessions/:proxy_session_id/acquisition_attempts/:acquisition_attempt_id/provider_objects";
+}, {
+    readonly method: "POST";
+    readonly operation: "providerAcquisitions.supersedeProviderAcquisition";
+    readonly path: "/proxy_sessions/:proxy_session_id/acquisition_attempts/:acquisition_attempt_id/supersede";
+}, {
+    readonly method: "GET";
+    readonly operation: "providerAcquisitions.listProviderAcquisitions";
+    readonly path: "/proxy_sessions/:proxy_session_id/acquisition_attempts";
+}];
+export declare class ProxyProviderAcquisitionsResource {
+    private readonly httpClient;
+    constructor(httpClient: ProxyCheckoutHttpClient);
+    reserveProviderAcquisition(proxySessionId: string, input: ReserveProviderAcquisitionInput): Promise<ProviderAcquisitionReservation>;
+    attachProviderAcquisitionObject(proxySessionId: string, acquisitionAttemptId: string, input: AttachProviderAcquisitionObjectInput): Promise<ProviderAcquisition>;
+    supersedeProviderAcquisition(proxySessionId: string, acquisitionAttemptId: string, input: SupersedeProviderAcquisitionInput): Promise<ProviderAcquisitionReservation>;
+    listProviderAcquisitions(proxySessionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<ProviderAcquisition[]>;
+}

package/dist/cjs/provider-acquisitions.d.ts

@@ -0,0 +1,98 @@
+import type { ProxyCheckoutHttpClient } from "./http-client.js";
+import type { ProxyCheckoutServerRequestOptions } from "./types.js";
+export type ProviderAcquisitionCommercialMode = "one_time" | "subscription";
+export type ProviderAcquisitionIntegrationPath = "checkout_session" | "direct_subscription" | "payment_intent";
+export type ProviderAcquisitionCheckoutUiMode = "custom" | "embedded" | "hosted";
+export type ProviderAcquisitionPricingMode = "fixed" | "provider_finalized";
+export type ProviderAcquisitionObjectType = "checkout_session" | "payment_intent" | "setup_intent" | "subscription";
+export interface ProviderAcquisition {
+    readonly attemptNumber: number;
+    readonly checkoutUiMode: ProviderAcquisitionCheckoutUiMode | "unknown" | null;
+    readonly commercialMode: ProviderAcquisitionCommercialMode;
+    readonly completionRecordedAt: string | null;
+    readonly createdAt: string;
+    readonly directFeeBasisSource: string | null;
+    readonly directMerchandiseCurrency: string | null;
+    readonly directMerchandiseSubtotalMinor: number | null;
+    readonly id: string;
+    readonly integrationPath: ProviderAcquisitionIntegrationPath;
+    readonly merchantPspConfigId: string;
+    readonly pricingMode: ProviderAcquisitionPricingMode;
+    readonly providerCreatedAt: string | null;
+    /** Stripe Customer ID retained only as a merchant-authenticated diagnostic. */
+    readonly providerCustomerId: string | null;
+    readonly providerRetryNotAfter: string;
+    readonly providerRootObjectId: string | null;
+    readonly providerRootObjectType: ProviderAcquisitionObjectType | null;
+    readonly providerSetupIntentId: string | null;
+    readonly proxySessionId: string;
+    readonly psp: "stripe";
+    readonly status: string;
+    readonly statusReason: string | null;
+    readonly supersedesAttemptId: string | null;
+    readonly updatedAt: string;
+    readonly version: number;
+}
+export interface ProviderAcquisitionReservation {
+    readonly acquisitionAttempt: ProviderAcquisition;
+    readonly stripe: {
+        readonly idempotencyKeys: {
+            readonly root: string;
+            readonly setupIntent?: string;
+        };
+        readonly metadata: {
+            readonly proxyAcquisitionAttemptId: string;
+            readonly proxyContractVersion: "2";
+            readonly proxySessionId: string;
+        };
+    };
+}
+export interface ReserveProviderAcquisitionInput extends ProxyCheckoutServerRequestOptions {
+    readonly checkoutUiMode?: ProviderAcquisitionCheckoutUiMode;
+    readonly commercialMode: ProviderAcquisitionCommercialMode;
+    readonly integrationPath: ProviderAcquisitionIntegrationPath;
+    /** Optional server-only direct PaymentIntent percentage basis; omit to use verified provider gross. */
+    readonly merchandiseSubtotalMinor?: number;
+    readonly pricingMode: ProviderAcquisitionPricingMode;
+    readonly providerOptionsFingerprint: string;
+}
+export interface AttachProviderAcquisitionObjectInput extends ProxyCheckoutServerRequestOptions {
+    readonly expectedVersion: number;
+    readonly objectId: string;
+    readonly objectType: ProviderAcquisitionObjectType;
+    readonly role: "root" | "setup_intent";
+}
+export interface SupersedeProviderAcquisitionInput extends ProxyCheckoutServerRequestOptions {
+    readonly expectedVersion: number;
+    readonly reason: string;
+    readonly replacement: {
+        readonly checkoutUiMode?: ProviderAcquisitionCheckoutUiMode;
+        readonly integrationPath: ProviderAcquisitionIntegrationPath;
+        readonly providerOptionsFingerprint: string;
+    };
+}
+export declare const proxyCheckoutProviderAcquisitionEndpoints: readonly [{
+    readonly method: "POST";
+    readonly operation: "providerAcquisitions.reserveProviderAcquisition";
+    readonly path: "/proxy_sessions/:proxy_session_id/acquisition_attempts";
+}, {
+    readonly method: "POST";
+    readonly operation: "providerAcquisitions.attachProviderAcquisitionObject";
+    readonly path: "/proxy_sessions/:proxy_session_id/acquisition_attempts/:acquisition_attempt_id/provider_objects";
+}, {
+    readonly method: "POST";
+    readonly operation: "providerAcquisitions.supersedeProviderAcquisition";
+    readonly path: "/proxy_sessions/:proxy_session_id/acquisition_attempts/:acquisition_attempt_id/supersede";
+}, {
+    readonly method: "GET";
+    readonly operation: "providerAcquisitions.listProviderAcquisitions";
+    readonly path: "/proxy_sessions/:proxy_session_id/acquisition_attempts";
+}];
+export declare class ProxyProviderAcquisitionsResource {
+    private readonly httpClient;
+    constructor(httpClient: ProxyCheckoutHttpClient);
+    reserveProviderAcquisition(proxySessionId: string, input: ReserveProviderAcquisitionInput): Promise<ProviderAcquisitionReservation>;
+    attachProviderAcquisitionObject(proxySessionId: string, acquisitionAttemptId: string, input: AttachProviderAcquisitionObjectInput): Promise<ProviderAcquisition>;
+    supersedeProviderAcquisition(proxySessionId: string, acquisitionAttemptId: string, input: SupersedeProviderAcquisitionInput): Promise<ProviderAcquisitionReservation>;
+    listProviderAcquisitions(proxySessionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<ProviderAcquisition[]>;
+}

package/dist/cjs/provider-acquisitions.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProxyProviderAcquisitionsResource = exports.proxyCheckoutProviderAcquisitionEndpoints = void 0;
+const response_validators_js_1 = require("./response-validators.js");
+exports.proxyCheckoutProviderAcquisitionEndpoints = [
+    {
+        method: "POST",
+        operation: "providerAcquisitions.reserveProviderAcquisition",
+        path: "/proxy_sessions/:proxy_session_id/acquisition_attempts",
+    },
+    {
+        method: "POST",
+        operation: "providerAcquisitions.attachProviderAcquisitionObject",
+        path: "/proxy_sessions/:proxy_session_id/acquisition_attempts/:acquisition_attempt_id/provider_objects",
+    },
+    {
+        method: "POST",
+        operation: "providerAcquisitions.supersedeProviderAcquisition",
+        path: "/proxy_sessions/:proxy_session_id/acquisition_attempts/:acquisition_attempt_id/supersede",
+    },
+    {
+        method: "GET",
+        operation: "providerAcquisitions.listProviderAcquisitions",
+        path: "/proxy_sessions/:proxy_session_id/acquisition_attempts",
+    },
+];
+class ProxyProviderAcquisitionsResource {
+    httpClient;
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    async reserveProviderAcquisition(proxySessionId, input) {
+        const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/acquisition_attempts`, {
+            ...(input.checkoutUiMode === undefined ? {} : { checkout_ui_mode: input.checkoutUiMode }),
+            commercial_mode: input.commercialMode,
+            integration_path: input.integrationPath,
+            ...(input.merchandiseSubtotalMinor === undefined
+                ? {}
+                : { merchandise_subtotal_minor: input.merchandiseSubtotalMinor }),
+            pricing_mode: input.pricingMode,
+            provider_options_fingerprint: input.providerOptionsFingerprint,
+        }, { requestId: input.requestId });
+        return parseReservation(response, "providerAcquisitions.reserveProviderAcquisition");
+    }
+    async attachProviderAcquisitionObject(proxySessionId, acquisitionAttemptId, input) {
+        const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/acquisition_attempts/${encodeURIComponent(acquisitionAttemptId)}/provider_objects`, {
+            expected_version: input.expectedVersion,
+            object_id: input.objectId,
+            object_type: input.objectType,
+            role: input.role,
+        }, { requestId: input.requestId });
+        return parseAcquisition(response, "providerAcquisitions.attachProviderAcquisitionObject");
+    }
+    async supersedeProviderAcquisition(proxySessionId, acquisitionAttemptId, input) {
+        const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/acquisition_attempts/${encodeURIComponent(acquisitionAttemptId)}/supersede`, {
+            expected_version: input.expectedVersion,
+            reason: input.reason,
+            replacement: {
+                ...(input.replacement.checkoutUiMode === undefined
+                    ? {}
+                    : { checkout_ui_mode: input.replacement.checkoutUiMode }),
+                integration_path: input.replacement.integrationPath,
+                provider_options_fingerprint: input.replacement.providerOptionsFingerprint,
+            },
+        }, { requestId: input.requestId });
+        return parseReservation(response, "providerAcquisitions.supersedeProviderAcquisition");
+    }
+    async listProviderAcquisitions(proxySessionId, options = {}) {
+        const response = await this.httpClient.request("GET", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/acquisition_attempts`, undefined, options);
+        const body = (0, response_validators_js_1.requireJsonObject)(response, "providerAcquisitions.listProviderAcquisitions");
+        if (!Array.isArray(body.data)) {
+            throw new Error("Proxy API response field providerAcquisitions.listProviderAcquisitions.data must be an array.");
+        }
+        return body.data.map((value, index) => parseAcquisition(value, `providerAcquisitions.listProviderAcquisitions.data[${index}]`));
+    }
+}
+exports.ProxyProviderAcquisitionsResource = ProxyProviderAcquisitionsResource;
+function parseReservation(value, operation) {
+    const body = (0, response_validators_js_1.requireJsonObject)(value, operation);
+    const stripe = (0, response_validators_js_1.requireJsonObject)(body.stripe, `${operation}.stripe`);
+    const idempotencyKeys = (0, response_validators_js_1.requireJsonObject)(stripe.idempotency_keys, `${operation}.stripe.idempotencyKeys`);
+    const metadata = (0, response_validators_js_1.requireJsonObject)(stripe.metadata, `${operation}.stripe.metadata`);
+    const contractVersion = (0, response_validators_js_1.requireString)(metadata.proxy_contract_version, `${operation}.stripe.metadata.proxyContractVersion`);
+    if (contractVersion !== "2") {
+        throw new Error(`Proxy API response field ${operation}.stripe.metadata.proxyContractVersion is unsupported.`);
+    }
+    const setupIntent = idempotencyKeys.setup_intent;
+    return {
+        acquisitionAttempt: parseAcquisition(body.acquisition_attempt, `${operation}.acquisitionAttempt`),
+        stripe: {
+            idempotencyKeys: {
+                root: (0, response_validators_js_1.requireString)(idempotencyKeys.root, `${operation}.stripe.idempotencyKeys.root`),
+                ...(setupIntent === undefined
+                    ? {}
+                    : {
+                        setupIntent: (0, response_validators_js_1.requireString)(setupIntent, `${operation}.stripe.idempotencyKeys.setupIntent`),
+                    }),
+            },
+            metadata: {
+                proxyAcquisitionAttemptId: (0, response_validators_js_1.requireString)(metadata.proxy_acquisition_attempt_id, `${operation}.stripe.metadata.proxyAcquisitionAttemptId`),
+                proxyContractVersion: contractVersion,
+                proxySessionId: (0, response_validators_js_1.requireString)(metadata.proxy_session_id, `${operation}.stripe.metadata.proxySessionId`),
+            },
+        },
+    };
+}
+function parseAcquisition(value, operation) {
+    const body = (0, response_validators_js_1.requireJsonObject)(value, operation);
+    return {
+        attemptNumber: (0, response_validators_js_1.requireInteger)(body.attempt_number, `${operation}.attemptNumber`),
+        checkoutUiMode: (0, response_validators_js_1.requireNullableString)(body.checkout_ui_mode, `${operation}.checkoutUiMode`),
+        commercialMode: (0, response_validators_js_1.requireString)(body.commercial_mode, `${operation}.commercialMode`),
+        completionRecordedAt: (0, response_validators_js_1.requireNullableString)(body.completion_recorded_at, `${operation}.completionRecordedAt`),
+        createdAt: (0, response_validators_js_1.requireString)(body.created_at, `${operation}.createdAt`),
+        directFeeBasisSource: (0, response_validators_js_1.requireNullableString)(body.direct_fee_basis_source, `${operation}.directFeeBasisSource`),
+        directMerchandiseCurrency: (0, response_validators_js_1.requireNullableString)(body.direct_merchandise_currency, `${operation}.directMerchandiseCurrency`),
+        directMerchandiseSubtotalMinor: (0, response_validators_js_1.requireNullableInteger)(body.direct_merchandise_subtotal_minor, `${operation}.directMerchandiseSubtotalMinor`),
+        id: (0, response_validators_js_1.requireString)(body.id, `${operation}.id`),
+        integrationPath: (0, response_validators_js_1.requireString)(body.integration_path, `${operation}.integrationPath`),
+        merchantPspConfigId: (0, response_validators_js_1.requireString)(body.merchant_psp_config_id, `${operation}.merchantPspConfigId`),
+        pricingMode: (0, response_validators_js_1.requireString)(body.pricing_mode, `${operation}.pricingMode`),
+        providerCreatedAt: (0, response_validators_js_1.requireNullableString)(body.provider_created_at, `${operation}.providerCreatedAt`),
+        providerCustomerId: (0, response_validators_js_1.requireNullableString)(body.provider_customer_id, `${operation}.providerCustomerId`),
+        providerRetryNotAfter: (0, response_validators_js_1.requireString)(body.provider_retry_not_after, `${operation}.providerRetryNotAfter`),
+        providerRootObjectId: (0, response_validators_js_1.requireNullableString)(body.provider_root_object_id, `${operation}.providerRootObjectId`),
+        providerRootObjectType: (0, response_validators_js_1.requireNullableString)(body.provider_root_object_type, `${operation}.providerRootObjectType`),
+        providerSetupIntentId: (0, response_validators_js_1.requireNullableString)(body.provider_setup_intent_id, `${operation}.providerSetupIntentId`),
+        proxySessionId: (0, response_validators_js_1.requireString)(body.proxy_session_id, `${operation}.proxySessionId`),
+        psp: (0, response_validators_js_1.requireString)(body.psp, `${operation}.psp`),
+        status: (0, response_validators_js_1.requireString)(body.status, `${operation}.status`),
+        statusReason: (0, response_validators_js_1.requireNullableString)(body.status_reason, `${operation}.statusReason`),
+        supersedesAttemptId: (0, response_validators_js_1.requireNullableString)(body.supersedes_attempt_id, `${operation}.supersedesAttemptId`),
+        updatedAt: (0, response_validators_js_1.requireString)(body.updated_at, `${operation}.updatedAt`),
+        version: (0, response_validators_js_1.requireInteger)(body.version, `${operation}.version`),
+    };
+}

package/dist/cjs/sessions.d.cts

@@ -37,6 +37,7 @@ export interface ProxySessionHandoff extends ProxySession {
     readonly status: "payer_handoff_pending" | "payer_opened";
 }
 export interface MerchantProxySession {
+    readonly actionableNextStep: ProxySessionActionableNextStep;
     readonly amountMinor: number;
     readonly beneficiaryContact: {
         readonly email: string | null;
@@ -45,8 +46,10 @@ export interface MerchantProxySession {
     readonly buyerReference: string;
     readonly cartSnapshot: JsonObject;
     readonly cartVersion: number;
+    readonly completedAcquisitionAttemptId: string | null;
     readonly createdAt: string;
     readonly currency: string;
+    readonly currentAcquisitionAttempt: ProxySessionAcquisitionSummary | null;
     readonly expiresAt: string;
     readonly id: string;
     readonly idempotencyKey: string | null;
@@ -57,14 +60,27 @@ export interface MerchantProxySession {
         readonly phone: string | null;
     } | null;
     readonly payerDestinationUrl: string | null;
+    readonly presentationState: ProxySessionPresentationState;
     readonly providerCheckoutSessionId: string | null;
     readonly providerCheckoutSessionPsp: string | null;
     readonly status: string;
     readonly updatedAt: string;
 }
+export interface ProxySessionAcquisitionSummary {
+    readonly attemptNumber: number;
+    readonly checkoutUiMode: string | null;
+    readonly id: string;
+    readonly integrationPath: string;
+    readonly status: string;
+    readonly statusReason: string | null;
+}
+export type ProxySessionActionableNextStep = "already_paid" | "continue_payment" | "merchant_action_required" | "prepare_provider" | "unavailable";
 export interface PayerOpenedResult extends MerchantProxySession {
-    readonly status: "payer_opened";
+    readonly presentationState: ProxySessionPresentationState;
+    readonly status: ProxySessionViewStatus;
 }
+export type ProxySessionPresentationState = "action_required" | "already_paid" | "checkout_available" | "unavailable";
+export type ProxySessionViewStatus = "cancelled" | "created" | "expired" | "failed" | "merchant_action_required" | "paid" | "payer_handoff_pending" | "payer_opened" | "payment_pending" | "provisionable" | "provisioned" | "provisioning_failed";
 /** A merchant session with its cart snapshot validated against a merchant schema. */
 export interface TypedMerchantProxySession<TCart> extends MerchantProxySession {
     readonly cart: TCart;
@@ -85,6 +101,8 @@ export interface ProxySessionCartResult {
     readonly currency: string;
 }
 export interface RecordProviderBindingInput extends ProxyCheckoutServerRequestOptions {
+    /** Checkout commercial mode used only to safely infer the deprecated binding into an acquisition. */
+    readonly commercialMode?: "one_time" | "subscription";
     readonly providerCheckoutSessionId: string;
     readonly psp: string;
 }

package/dist/cjs/sessions.d.ts

@@ -37,6 +37,7 @@ export interface ProxySessionHandoff extends ProxySession {
     readonly status: "payer_handoff_pending" | "payer_opened";
 }
 export interface MerchantProxySession {
+    readonly actionableNextStep: ProxySessionActionableNextStep;
     readonly amountMinor: number;
     readonly beneficiaryContact: {
         readonly email: string | null;
@@ -45,8 +46,10 @@ export interface MerchantProxySession {
     readonly buyerReference: string;
     readonly cartSnapshot: JsonObject;
     readonly cartVersion: number;
+    readonly completedAcquisitionAttemptId: string | null;
     readonly createdAt: string;
     readonly currency: string;
+    readonly currentAcquisitionAttempt: ProxySessionAcquisitionSummary | null;
     readonly expiresAt: string;
     readonly id: string;
     readonly idempotencyKey: string | null;
@@ -57,14 +60,27 @@ export interface MerchantProxySession {
         readonly phone: string | null;
     } | null;
     readonly payerDestinationUrl: string | null;
+    readonly presentationState: ProxySessionPresentationState;
     readonly providerCheckoutSessionId: string | null;
     readonly providerCheckoutSessionPsp: string | null;
     readonly status: string;
     readonly updatedAt: string;
 }
+export interface ProxySessionAcquisitionSummary {
+    readonly attemptNumber: number;
+    readonly checkoutUiMode: string | null;
+    readonly id: string;
+    readonly integrationPath: string;
+    readonly status: string;
+    readonly statusReason: string | null;
+}
+export type ProxySessionActionableNextStep = "already_paid" | "continue_payment" | "merchant_action_required" | "prepare_provider" | "unavailable";
 export interface PayerOpenedResult extends MerchantProxySession {
-    readonly status: "payer_opened";
+    readonly presentationState: ProxySessionPresentationState;
+    readonly status: ProxySessionViewStatus;
 }
+export type ProxySessionPresentationState = "action_required" | "already_paid" | "checkout_available" | "unavailable";
+export type ProxySessionViewStatus = "cancelled" | "created" | "expired" | "failed" | "merchant_action_required" | "paid" | "payer_handoff_pending" | "payer_opened" | "payment_pending" | "provisionable" | "provisioned" | "provisioning_failed";
 /** A merchant session with its cart snapshot validated against a merchant schema. */
 export interface TypedMerchantProxySession<TCart> extends MerchantProxySession {
     readonly cart: TCart;
@@ -85,6 +101,8 @@ export interface ProxySessionCartResult {
     readonly currency: string;
 }
 export interface RecordProviderBindingInput extends ProxyCheckoutServerRequestOptions {
+    /** Checkout commercial mode used only to safely infer the deprecated binding into an acquisition. */
+    readonly commercialMode?: "one_time" | "subscription";
     readonly providerCheckoutSessionId: string;
     readonly psp: string;
 }