# Agent workflow: another processor to the Stripe-shaped contract, then Knox

Use this when the active application integrates a provider other than Stripe. Test mode only; keep production on the incumbent.
The agent performs the adaptation and tests, then follows the shared Stripe-to-Knox migration workflow.
Stripe is the intermediate software contract. Do not require a Stripe account or an intermediate production cutover to build that contract.

## 1. Understand the incumbent integration

Trace actual provider calls and payment paths; installed packages alone do not identify the active processor.
Find the order model, server amount/currency authority, authorization/capture behavior, browser payment collection,
3DS/redirect handling, refunds, signed callbacks, idempotency, saved cards, subscriptions and settlement/reconciliation.
Run existing tests and keep their behavior as the baseline. Ask for missing business intent or private access; make the code edits yourself.

Build an explicit mapping with evidence for each capability:

| Existing behavior | Stripe-shaped target |
|---|---|
| Purchase/payment attempt | PaymentIntent lifecycle and statuses |
| Authorization then settlement | manual capture and PaymentIntent capture |
| Customer and stored payment reference | Customer/PaymentMethod with explicit provider-owned ID mapping |
| Browser tokenization/3DS | hosted fields, client_secret confirmation and next_action |
| Refund | Refund linked to the payment's owning provider |
| Provider callback | verified event -> normalized state transition -> idempotent fulfillment |
| Request deduplication | stable per-attempt idempotency key and durable attempt reservation |
| Recurring billing | supported Subscription/Invoice/Price semantics or an explicitly blocked cohort |

This is behavioral translation, not a brand or URL replacement. Preserve provider-specific states until their transitions are mapped.
For a missing required capability, report a compatibility blocker; do not label unsupported operations equivalent.

## 2. Create the common payment boundary

Add a focused server adapter or refactor at the existing payment boundary so order/fulfillment code speaks the Stripe-shaped contract.
Keep an incumbent adapter implementing that contract through the original provider and its original hosted collection/signature logic.
Keep credentials separated by provider; do not rename the incumbent's secret environment values into Knox values.
Write contract tests comparing authorize/capture, decline, async/3DS, refund and duplicate webhook/idempotency outcomes as applicable.
Only implement capabilities the customer uses and Knox actually supports; leave unrelated code unchanged.
Keep the existing processor selected by default. Never introduce raw card fields to make the adapter uniform.

## 3. Continue into the shared Stripe-to-Knox workflow

Read https://docs.knoxapi.com/agent-setup/stripe-to-knox.md.
The application now has the common contract used by that workflow; start its parallel Knox integration, ownership mapping,
sandbox verification, traffic-switch preparation and staged migration policy. The incumbent arm is still the original processor.
Use https://docs.knoxapi.com/openapi/knox.json for operation availability and https://meta.knoxapi.com/v1 for migration control.
Do not tell the merchant to migrate manually or ask them to choose an integration pattern.

No SDK can transfer a provider's private vault tokens by changing endpoint names. Keep existing saved-card/subscription cohorts
at their original owner until a separate authorized mapping/vault transfer or customer recollection is verified.
Never move a possibly charged retry to another provider. Never reuse an old provider's payment ID as a Knox payment ID.

## Completion evidence

Produce the behavior mapping, baseline and adapter contract tests, a verified Knox sandbox checkout with webhook fulfillment,
the nonsecret migration report from the shared workflow, and explicit outstanding provider/data/Knox capability blockers.
`sandbox_verified` means the code adaptation works in sandbox. `migration_complete` requires the later real traffic and data checks.
