Stripe compatibility

Proxy supports delegated one-time payments and subscriptions without becoming the merchant of record or taking control of your Stripe account. Your authenticated merchant server creates every Stripe PaymentIntent, SetupIntent, Checkout Session, and Subscription. Proxy’s public API and workers never create, cancel, refund, or dispute a Stripe object.

Stripe acquisition is generally available

Implemented acquisition paths are enabled by default on one Stripe configuration. Capability IDs select routing, compatibility, permissions, events, and fail-closed dependencies; they are not cohort grants or per-merchant approvals. Webhook Endpoint verification remains visible advisory health and does not gate acquisition.

Supported paths

Path	Use
Direct PaymentIntent	Fixed-price one-time payment using your existing Payment Element flow.
Hosted Checkout	One-time or subscription Checkout using Stripe’s hosted page.
Embedded Checkout	One-time or subscription Checkout rendered in your application.
Custom Checkout	One-time or subscription Checkout rendered with Stripe’s Checkout-based Elements components.
Direct Subscription with SetupIntent	Prepare a reusable payment method, then create the Subscription on your server. SetupIntent success is not payment or fulfillment evidence.
Direct Subscription with saved payment method	Create the Subscription on your server using an already saved method; Proxy does not require or invent a SetupIntent.

Hosted, embedded, and custom Checkout share one server-side Checkout acquisition contract. Presentation mode does not change payment, lifecycle, fulfillment, or fee semantics.

Exact compatibility floors

The exact minimums and availability below render from Proxy’s generated capability manifest. The release matrix proves coherent classic, embedded-floor, custom-floor, and dated-current package sets; do not construct an untested set by mixing package versions from different lanes.

These tables render capability manifest v2 and parser contract v2. Proxy configuration and stripe doctor use the same generated source.

Capability	Path	Availability	stripe-node / request API	Stripe.js / React Stripe.js
setup.webhook_endpoint_verification	Supporting capability	general_availability	12.18.0 / 2022-11-15	Not used / Not used
one_time.direct_payment_intent	OT-PI	general_availability	12.18.0 / 2022-11-15	2.4.0 / 2.9.0
one_time.checkout.hosted	OT-CO-H	general_availability	12.18.0 / 2022-11-15	2.4.0 / 2.9.0
one_time.checkout.embedded	OT-CO-E	general_availability	14.0.0 / 2023-10-16	2.1.8 / 2.3.2
one_time.checkout.custom	OT-CO-C	general_availability	18.0.0 / 2025-03-31.basil	7.0.0 / 3.6.0
subscription.direct_setup_intent	SUB-SI	general_availability	12.18.0 / 2022-11-15	2.4.0 / 2.9.0
subscription.direct_saved_payment_method	SUB-SAVED	general_availability	12.18.0 / 2022-11-15	2.4.0 / 2.9.0
subscription.checkout.hosted	SUB-CO-H	general_availability	12.18.0 / 2022-11-15	2.4.0 / 2.9.0
subscription.checkout.embedded	SUB-CO-E	general_availability	14.0.0 / 2023-10-16	2.1.8 / 2.3.2
subscription.checkout.custom	SUB-CO-C	general_availability	18.0.0 / 2025-03-31.basil	7.0.0 / 3.6.0
lifecycle.refunds	Supporting capability	observation_only	12.18.0 / 2022-11-15	Not used / Not used
lifecycle.disputes	Supporting capability	observation_only	12.18.0 / 2022-11-15	Not used / Not used
reconciliation.legacy_metadata_search	Supporting capability	general_availability	12.18.0 / 2022-11-15	Not used / Not used

If a version descriptor is below the selected presentation floor, upgrade the coherent lane or choose a supported presentation such as hosted Checkout. Do not silence compatibility preflight with an API-version override while retaining an incompatible server or browser package.

Your dedicated Proxy Webhook Endpoint’s API version is an independent compatibility axis. It does not need to equal the API version pinned on your merchant-server create request. Proxy selects the generated event profile and bounded payload decoder from the endpoint/Event version and supports the documented classic, embedded-generation, Basil, and dated-current payload lanes. A signed Event with an unrecognized or supported-but-malformed shape is retained as a visible failure; it is not silently treated as payment.

One purchase, one shared root

Create one durable purchase-request record in your system before creating the Proxy session. Reuse that business purchase ID as the Proxy session idempotency key for retries and for every person invited to pay for that same intended purchase. A genuinely new purchase gets a new purchase ID, even when buyer, cart, and amount are identical.

Cross-session identity

buyerReference identifies the merchant-owned beneficiary; it is not the purchase idempotency key and does not merge separate sessions. A Stripe Customer or PaymentMethod reference is diagnostic/provider evidence, not Proxy identity, cart ownership, completion, or fulfillment authority. Reusing the same buyer, Customer, or payment method across two genuinely different purchases therefore creates two distinct Proxy sessions and cannot cause one purchase to fulfill the other.

Proxy reserves or joins one active acquisition for that session before your server creates Stripe state. Use the returned provider idempotency keys exactly; do not derive alternatives. After creation, attach the root through the same server-side SDK/API owner. The browser receives only Stripe’s publishable presentation material, such as a client secret where the selected Stripe UI requires it.

Multiple viewers may open and render the same handoff concurrently. Opening a link does not acquire a payer lease, viewer lock, or leader role. Keep the shared cart editable until qualifying payment evidence completes the session. The first qualifying payment wins fulfillment; a later distinct successful financial object remains visible and fee-bearing but cannot create a second fulfillment grant.

Subscription completion and lifecycle

A Checkout Session or Subscription ID alone is not payment evidence. Initial completion comes from a supported positive paid Invoice, or from the accepted zero/no-payment-required trial rule. An initial Invoice that requires action or fails remains non-granting until the same Invoice becomes conclusively paid.

After initial completion, Proxy continues to retain supported renewal, retry, proration, trial-ending, pause/resume, cancellation, and configuration-change evidence. Every distinct supported positive paid Invoice is a financial fact. Zero Invoices and trial-only starts are lifecycle evidence but do not fabricate a payment or fee.

V1 does not treat metered billing, send_invoice, paid-out-of-band Invoice claims, multiple paid Invoice children, PaymentRecord/Charge-only allocations, or truncated Invoice payment collections as conclusive payment. Proxy retains the bounded evidence and reports reconciliation/action-required state instead.

Fulfillment ownership

Your application owns fulfillment and entitlement state. Consume Proxy’s signed merchant events idempotently, then retrieve current Proxy state before applying one business fulfillment transition. A return URL, browser callback, SetupIntent success, or client-side Stripe result never grants access by itself.

Refunds and disputes are observation only. They do not reverse an earned Proxy fee and Proxy does not automatically fulfill, revoke, cancel, refund, or manage a dispute for you. Your application decides whether those observations change access or fulfillment.

Fee policy

Proxy earns a fee for every distinct successful positive supported PaymentIntent or Invoice:

3% of the immutable merchandise basis + 30 minor currency units

One-time Checkout uses Stripe’s provider-authored Checkout merchandise subtotal. Direct PaymentIntent uses verified provider gross unless your authenticated server pins the optional merchandise-subtotal override when reserving the acquisition. Subscription payments use the supported Stripe Invoice line basis. The fee is recorded once against the financial object and is not reversed by a later refund or dispute. Zero/no-cost and trial-only objects earn no fee.

Permissions, events, and local development

Use a dedicated restricted Stripe key for Proxy reads; keep your unrestricted creation key on your merchant server. One customer setup validates the combined read-permission and Webhook Endpoint event union for every implemented Stripe acquisition path on the configuration. See Stripe events and permissions.

For local development, use proxy listen --stripe. It obtains the current sorted event profile from Proxy, supervises Stripe-to- merchant and Stripe-to-Proxy ingress, and forwards Proxy’s canonically signed merchant events to localhost. A stale capability profile fails before a temporary webhook secret is stored.

Agent-friendly integration sequence

1. Choose one path and one coherent version lane; run proxy stripe doctor for its exact compatibility, permission, and event requirements.
2. Create or recover one durable merchant-owned purchase request and one Proxy session for the intended purchase.
3. On the payer page, retrieve payer-safe shared session/cart state. Do not make a viewer the owner.
4. On your authenticated server, reserve or join the acquisition before calling Stripe.
5. Create the Stripe object with the returned Proxy metadata and idempotency keys, then attach the root through the same SDK/API owner.
6. Render the selected Stripe presentation and submit normally. Never send an unrestricted Stripe key, card data outside Stripe.js, or a Proxy secret key to the browser. Resolve Customer and PaymentMethod references on your server; never accept a browser-supplied reference as ownership or completion evidence.
7. Receive your independent Stripe webhook, Proxy’s Stripe ingress, and Proxy’s signed merchant event as separate delivery legs. Deduplicate all three.
8. Retrieve current Proxy state and perform one idempotent merchant fulfillment action when qualifying evidence exists.
9. Test success, zero/trial, action-required/failure recovery, renewal, refund/dispute observation, replay/reordering, and two simultaneous browser contexts before relying on the integration in production.

Legacy compatibility and deprecation

Proxy currently retains legacy Checkout binding adoption and bounded legacy PaymentIntent metadata search for older integrations. New reservation-based paths do not depend on metadata search. Legacy compatibility remains available until its usage telemetry is zero across a complete reviewed deprecation window, all supported clients are above the published floor, no unexplained old/new planner divergence remains, and a separate removal release is approved.

Do not delete legacy generic provider-binding columns based only on Stripe traffic: Shopify also uses those shared projections and requires a separate cross-PSP migration before physical removal.