Coding-agent integration handoff

Use this handoff when a coding agent will inspect an application and implement Proxy. The agent should make the provider and payment-flow decision from plain facts, then use the technical ID only to retrieve canonical requirements.

Copy this handoff

Integrate Proxy into this application without changing its payment ownership.

First report:
1. Provider: Stripe or Shopify.
2. Purchase type: one-time payments, subscriptions, or both.
3. For Stripe, whether a Checkout Session creates the PaymentIntent/Subscription
   or this application's server creates the Stripe object directly.
4. For Checkout, whether the payer uses hosted, embedded, or custom/Elements UI.
5. The exact existing routes/components that create the cart, start payment,
   receive provider events, and grant fulfillment or access.

Then:
- Read https://docs.proxycheckout.com/integration-paths.json.
- Select the human path before using its technical ID.
- Follow the linked terminal guide and its prerequisites.
- Use Node.js 22 or newer before installing or running the Proxy CLI.
- If the `proxy` command is not installed, run
  `npm install --global @proxy-checkout/cli`.
- For Stripe, run `proxy stripe doctor --path <id> --format json`.
- Install `stripe` with an exact version equal to `server_sdk` in that doctor
  report before copying the selected backend example.
- For embedded or custom Checkout, install `@stripe/stripe-js` and
  `@stripe/react-stripe-js` with exact versions equal to `browser_sdk` and
  `react_sdk` in that doctor report before copying client code.
- Implement one durable Proxy handoff per intended order.
- Validate ready, completed/already-paid, action-required, unavailable, retry,
  duplicate-event, and two-viewer behavior where the guide requires it.
- Do not fulfill from a browser redirect or expose server/provider secrets.
- If Shopify access is limited and no approved install link exists, stop and
  hand that availability step to a human; do not invent a custom-app path.

Return the selected path, files changed, commands run, observed test evidence,
and any prerequisite that still needs a human.

Agent decision sequence

1. Inspect the application’s existing cart and payment code. Do not infer the Stripe path from the visual component alone.
2. Choose stripe or shopify from the provider that owns final checkout.
3. For Stripe, choose one-time payments, subscriptions, or one path for each.
4. Decide whether a Checkout Session creates the PaymentIntent/Subscription or the application creates it directly.
5. Only for Checkout, choose hosted, embedded, or custom presentation.
6. Read the selected guide from the machine index and validate canonical requirements with stripe doctor.
7. Map Proxy’s handoff, payer return, provider events, and idempotent fulfillment onto existing application owners.
8. Implement and run the guide’s validation checklist.

Custom Elements can still be Checkout

When the application creates a Checkout Session and renders a custom Elements-based Checkout UI, select custom Checkout. For a subscription that is technical path SUB-CO-C; do not misclassify it as a direct subscription merely because Elements are visible.

Machine-readable sources

• /integration-paths.json is the small provider/path routing index with human labels, guide URLs, current Shopify availability, technical IDs, and validation commands.
• /stripe-integration-capabilities.json is the generated canonical Stripe capability manifest used by the docs, configuration, CLI, and SDK checks.
• /llms.txt is the compact public documentation map.
• proxy commands schema --format json returns the versioned CLI command registry.
• proxy --llms-full returns the CLI’s agent-oriented command reference.
• Node.js 22 or newer is required by the public Proxy CLI.
• npm install --global @proxy-checkout/cli installs the public proxy command used by the following checks.
• proxy stripe doctor --path <id> --format json returns exact versions, permissions, provider operations, events, availability, and unsupported options without credentials.
• The selected terminal guide generates exact stripe and, where needed, Stripe browser-package install commands from those canonical versions.

Do not scrape the advanced HTML matrix or copy capability facts into project instructions. Link to or generate from these sources so later production-test evidence and compatibility updates do not require another routing rewrite.

Required implementation evidence

The agent’s final report should show:

• the provider and selected human path, with technical ID only as supporting detail;
• the existing code owner for cart creation, provider object creation, event handling, and fulfillment;
• prerequisites that were validated versus those a human must complete;
• one intended order producing one recoverable Proxy handoff;
• the expected payer presentation;
• signed event/retry evidence and one idempotent fulfillment result; and
• clear next actions for test mode, live approval, or Shopify availability.