Set up Stripe

Complete this setup once before implementing a Stripe path. It connects Stripe to Proxy and configures the credentials, Stripe events, payer destination, and shared SDKs used by every supported one-time and subscription flow.

Before you code

The Proxy CLI requires Node.js 22 or newer. Confirm the runtime and install the public CLI:

node --version
npm install --global @proxy-checkout/cli

After you find your integration path, run the proxy stripe doctor --path … --format json command in that guide. It reports the path’s canonical compatibility requirements.

One Stripe configuration with valid credentials includes every implemented one-time and subscription path; no Proxy operator enables paths individually. Webhook endpoint verification reports setup health but never disables an acquisition path. Validate in Stripe test mode; live mode requires separate approval.

Connect Stripe to Proxy

Open Payment providers in the Proxy dashboard. In the Stripe section, enter:

• Your Stripe account ID
• Your Stripe publishable key
• A dedicated Stripe restricted key for Proxy reconciliation

Do not use your application's unrestricted secret key

Create a separate restricted key for Proxy. If this credential is compromised, its permissions determine the Stripe-account blast radius.

In Stripe’s API keys settings, create a restricted key with this exact manifest:

Stripe resource	Access
Checkout Sessions	Read
Invoices	Read
Payment Intents	Read
Setup Intents	Read
Subscriptions	Read
Webhook Endpoints	Read

Leave every other Stripe permission set to None. Permission manifest v2.

Proxy uses this credential only for the exact read operations required to reconcile PaymentIntents, hosted/embedded/custom Checkout Sessions, SetupIntents, Subscriptions, and Invoices and to check the configured Webhook Endpoint. It is separate from:

• your application’s server-side Stripe key used to create SetupIntents, PaymentIntents, Checkout Sessions, or subscriptions;
• the Stripe publishable key used by Stripe Elements; and
• the webhook signing secret copied from the Stripe webhook endpoint.

Use Stripe keys that match the current Proxy merchant mode. Test merchants require rk_test_ plus pk_test_ if you provide a publishable key. Live merchants require rk_live_ plus pk_live_. Set up test and live payment providers separately, including separate restricted keys, Stripe webhook endpoints, and signing secrets.

Proxy runs the exact list probes for the capabilities being configured before saving the connection. An invalid or under-permissioned key is rejected immediately with per-operation setup guidance; response bodies and provider objects are never persisted by the setup check.

The permission table above is the complete default profile for every implemented one-time and subscription path. Direct SetupIntent and saved-method subscriptions do not grant Proxy Customer or Payment Methods access. See Stripe direct subscriptions or Stripe-hosted subscriptions for the operations and events used by those paths.

If you connected Stripe before direct subscriptions became generally available, re-save or rotate the restricted key once before using those paths. Proxy validates the expanded read profile and then makes both direct-subscription branches available; webhook endpoint verification remains advisory.

Send Stripe events to Proxy

Configure a Stripe webhook endpoint that sends payment and subscription events to Proxy. Webhook setup is strongly recommended but is not an activation gate. An unverified endpoint remains visibly action_required in Proxy while every implemented acquisition path stays available. Without the required events, Proxy may not observe lifecycle changes, so its lifecycle and reconciliation state can remain stale.

In Payment providers, add a webhook config and enter a route key. Proxy shows the destination URL as soon as the route key is set. Copy that URL, but keep the Proxy form open.

In Stripe’s Webhooks dashboard, create an endpoint that sends events to the Proxy destination URL. Use your account as the event destination scope, choose an API version supported by the capability profile, select the exact sorted event union shown by Proxy, and choose Webhook endpoint as the destination type.

After Stripe creates the endpoint, copy its signing secret. Paste it into the Proxy webhook secret field and create the webhook config. proxy listen --stripe derives the same event union from the configuration and rejects a stale profile.

Create Proxy API keys

Head over to the API Keys section of your Proxy dashboard and create a secret key and a publishable key. Our SDKs will use these keys to connect to Proxy.

Configure the payer destination

A handoff is the Proxy-hosted payment link the buyer shares when someone else needs to pay. Proxy uses this setup to know what name to show on that link and where to send the payer after they open it.

In the Hosted handoff section, save these required fields:

• Display name: the merchant or product name shown to the payer
• Default checkout URL: the default page in your app where the payer completes checkout
• Allowed destination hosts: the domains Proxy is allowed to forward payers to

The default checkout URL’s domain must be included in Allowed destination hosts. Save this before creating payment links; without it, Proxy cannot create a shareable handoff link.

See Hosted Handoff for the Logo, Title, Description, and Site name fields, plus custom-domain preview behavior.

Install SDKs

For your backend apps:

JS Backend

npm

npm install @proxy-checkout/server-js @proxy-checkout/stripe-server-js

pnpm

pnpm add @proxy-checkout/server-js @proxy-checkout/stripe-server-js

yarn

yarn add @proxy-checkout/server-js @proxy-checkout/stripe-server-js

Other Languages

We currently don’t have SDKs for other languages. Refer to the API reference for the available endpoints.

The selected terminal section also provides a stripe install command pinned to the server_sdk version reported by stripe doctor. Run it before copying that path’s backend example; do not install an unversioned current Stripe SDK and report an older compatibility lane.

---

For your checkout frontend, install the Proxy client:

npm

npm install @proxy-checkout/client-js

pnpm

pnpm add @proxy-checkout/client-js

yarn

yarn add @proxy-checkout/client-js

Embedded Checkout and Elements paths also need Stripe’s browser packages. The selected terminal section provides exact install commands generated from the same canonical versions as stripe doctor; run them before copying its client example.

Verify setup

1. Confirm the Stripe connection is saved with the dedicated restricted key and matching test or live credentials.
2. Confirm Stripe sends the required events to the destination URL shown by Proxy and Proxy recognizes the signing secret.
3. Confirm the Proxy secret and publishable keys are available to the applications that need them.
4. Confirm the default checkout URL and its host are saved in Hosted handoff.
5. Confirm the shared SDKs install successfully in your backend and checkout frontend.

Setup is complete. Find your integration path, then create a handoff with the cart shape for that path.