# Agent workflow: migrate a Stripe application to Knox

Use this after inspecting the application's active Stripe payment paths. Complete the changes yourself in a branch.
Test mode only; leave production traffic on its existing provider. Do not ask the customer to perform routine code edits.
Preserve Stripe SDK imports on the server. An API-compatible code migration and a processor/card-data migration are separate tasks.

## 1. Inventory and prove compatibility

Trace server SDK calls, browser components, webhook handlers, persisted IDs, saved cards, subscriptions, refunds,
authorization/capture, 3DS and asynchronous payment completion. Record the concrete files and supported behaviors.
Record ownership for existing payments, customers, methods, subscriptions and historical refunds/disputes.
Keep this inventory free of keys, client secrets and personal data.

Compare every used endpoint/parameter and expected response with https://docs.knoxapi.com/openapi/knox.json.
Knox's supported API surface is a subset; route presence alone does not prove equivalent business behavior.
Record the Stripe API version the application uses: the SDK's pinned version, any `Stripe-Version` or `stripe_version`
override, and each webhook endpoint's `api_version`. Knox serves 2026-03-25.dahlia, 2026-04-22.dahlia,
2026-05-27.dahlia, 2026-06-24.dahlia, 2026-07-29.dahlia and 2026-08-26.dahlia; the live list is in llms.txt and
openapi/knox.json. An application on an older version (clover or earlier, or a plain date) must be upgraded to one of
these before it moves to Knox: report that as a compatibility blocker rather than overriding the version silently.
Run the incumbent tests as a baseline, then run those same behaviors against Knox's sandbox.
If a required behavior fails or is unavailable, report a Knox compatibility blocker. Do not silently remove the feature.
Do not run a project-wide regex rename: it can change server SDK imports, existing IDs and unrelated business code.

## 2. Add a parallel Knox integration

- Retain the Stripe server SDK and incumbent client configuration. Add a separate client using `KNOX_SECRET_KEY`
  and https://api.knoxapi.com. The SDK still appends `/v1`; use the SDK examples in the main setup guide.
- Keep the incumbent browser checkout intact. Add Knox's hosted browser SDK at https://api.knoxapi.com/js/v1/knox.js,
  Knox publishable keys and hosted card fields for the Knox arm. Do not point Stripe.js at Knox or assume unpublished npm packages exist.
  Match the existing UX and amounts/currency instead of replacing the checkout with a new unrelated template.
- Keep incumbent webhook verification and fulfillment. Register a separate Knox webhook endpoint with its own signing secret.
  Verify each provider's signature against that provider's secret; deduplicate fulfillment across both arms at the order level.
- Preserve the existing payment path until Knox's sandbox payment, browser confirmation, 3DS where applicable,
  capture/refund, webhook delivery and fulfillment tests pass. Run the Payments setup guide's integration-status check too.
  Existing workspace activity is not evidence that this application's replacement works.

## 3. Preserve provider ownership and payment state

Create a durable mapping in the merchant app before moving any traffic. For each payment attempt, persist:
the chosen provider arm (`incumbent` or `knox`), source/destination object IDs, order ID, idempotency key and migration state.
Reserve the payment attempt transactionally before the external call so concurrent retries do not select different providers.
Use the stored owner for retrieval, capture, cancel, refund, disputes and webhook fulfillment. Never reassign an existing attempt.
A timeout after sending a payment request is an unknown outcome: query/reconcile with the same provider and idempotency key.
Never retry a possibly charged request at the other provider.

Stripe `cus_`, `pm_`, `pi_`, subscription IDs and webhook secrets are not automatically Knox objects just because the API shapes match.
Never replay existing Stripe IDs at Knox without an implemented, verified mapping/import path.
Existing refunds/disputes and subscriptions stay with their original owner until separately migrated and reconciled.
For saved cards, identify an authorized provider/vault transfer or a customer recollection path. Never export PAN/CVC through the agent.
An existing Stripe processor account behind Meta does not by itself prove that Stripe payment-method tokens can be reused by Knox.
Knox's saved-card/vault migration is not a finished automated feature. Record it as a blocker for affected cohorts.
Reference: https://docs.stripe.com/get-started/data-migrations/overview.

## 4. Prepare an autonomous staged migration

Download and read the standalone helper appropriate to the app:
- Python: https://docs.knoxapi.com/agent-setup/tools/knox-switch.py (requires project-local `httpx`).
- Node: https://docs.knoxapi.com/agent-setup/tools/knox-switch.mjs (Node 18+ with `fetch` and `AbortSignal.timeout`).

Copy the helper into an appropriate server module using the project's naming convention; preserve existing customized helpers.
Configure its control origin as https://meta.knoxapi.com, with the default `/v1` control prefix.
Local backend tests may pass `control_prefix="/knox/v1"` (Node `controlPrefix`) explicitly.
The helper selects the arm before a new payment; pass the persisted `existing_arm` (Node `existingArm`) on retries.
It never calls either payment provider for you, and it does not replace the durable application mapping.
The default control cache lasts 60 seconds, so pause/rollback propagation can take that long; configure a shorter TTL
if the agreed policy requires it. After the cached state expires, a failed or invalid refresh sends new assignments
to the incumbent. Existing attempts remain with their stored owner.
Observe authorized/declined/error outcomes and timings from both arms; observe/reconcile timeouts before labeling an outcome.
Flush observations periodically and on graceful shutdown, including low-volume batches. Each flush sends at most 500 records.
The helper's pending observations are in memory, not durable or guaranteed exactly once. For an authorized production ramp,
add durable attempt/outcome reporting and reconcile missing or duplicate observations before using them to advance traffic.

Leave the traffic ramp paused at 0% during setup. Read `GET https://meta.knoxapi.com/v1/traffic/ramp` and its actual `schedule`.
The server schedule is 1%, 2%, 3%, 5%, 8%, 13%, 21%, 34%, 55%, 89%, 100%. Steps above 8% also need a one-sided 95% non-inferiority test on authorization and error rates, and for 7 days after a rollback each step up needs a signed-in dashboard user; an API key cannot advance it then, and a restricted key never can.
Live processing is disabled in this deployment. Do not claim a completed production migration or invent unsupported ramp steps.

Prepare one customer-approved migration policy covering eligible cohorts, maximum share, minimum observations,
authorization/error/latency thresholds, automatic rollback and a hold period for retiring the incumbent.
Once live processing and the complete schedule are available and that policy is authorized, the agent can operate the supported
`/traffic/ramp/advance`, `/pause`, `/resume`, `/rollback`, `/evaluate` actions within it; no human code editing is required.
Keep saved-card/subscription cohorts at the incumbent until their independent migration is verified.

## Completion evidence

Write a nonsecret migration report: baseline tests, changed files, endpoint/behavior coverage, object-owner mapping,
new sandbox payment/event IDs, application-specific fulfillment evidence, readiness checks, ramp state and rollback procedure.
Report `sandbox_verified` only after these checks pass. Report blocked cohorts explicitly.
Report `migration_complete` only after real authorized traffic reaches the agreed final share, reconciliation passes,
subscriptions/saved cards are addressed, and the incumbent retirement conditions have been satisfied.
