Payment Orchestration

The Checkout Code Trap: Vendor Lock-in and Auth Rate Drift

You wrote the checkout flow six months ago. It calls stripe.charges.create. It works. Until it doesn't.

A regional bank flags your volume. Auth rates dip to 78%. You need to route to a local acquirer. Now you're rewriting the adapter layer, mapping ISO 20022 fields, and praying your idempotency keys survive the refactor. You're not a payments company; you're a SaaS or marketplace trying to ship features, but your checkout code is a tangled mess of vendor-specific SDKs. We built the Payment Orchestration Pack because engineering teams shouldn't be reinventing the routing logic wheel every time a processor changes its API contract. An orchestration layer sits between your app and multiple processors, gateways, and acquiring banks, abstracting the vendor noise into a single control plane ^[1].

If you're running a complex multi-vendor marketplace architecture, this fragility compounds across every vendor's payout logic. You end up with webhook signature validation drift, mismatched error formats, and retry logic that races against itself. The skill.md file in this pack defines the full workflow, guiding the agent through requirements gathering, gateway selection, architecture design, SDK integration, orchestration logic, and compliance validation. You get a structured path instead of a GitHub issue backlog.

Why Hardcoding Gateways Bleeds Revenue and Scope

Ignoring this isn't just technical debt; it's bleeding revenue. Every percentage point of auth rate loss is direct churn. Smart routing can mitigate revenue loss and increase auth rates by 50-70 basis points on average ^[5]. When you're hardcoding, you're blind to that lift. You're manually routing based on heuristics that don't scale, missing the optimization opportunities that a proper orchestrator provides.

You're also walking into compliance landmines. If you're storing raw PANs because your adapter logic is scattered across three microservices, you just expanded your PCI DSS scope. You're handling tokenization and vaulting logic manually, adding integration layers and costs without the future-proofing a proper orchestrator provides ^[4]. The references/compliance-and-security.md file gives you the canonical knowledge on PCI DSS requirements, data minimization, tokenization, and regional compliance like GDPR and PSD2. You don't have to hunt for the latest audit checklist.

And when a gateway goes down? Your checkout hangs. You lose the sale. Payment orchestration adds redundancy and control, preventing single points of failure from becoming revenue black holes ^[3]. For subscription-based models, settlement delays and failed retries can cascade into dunning loops that destroy LTV, which is why subscription commerce workflows demand a resilient orchestration layer from day one. Improved cash flow comes from simplifying payment processes and optimizing routing for faster settlement, something a manual integration can't guarantee ^[2].

A Cross-Border Marketplace's Routing Nightmare

Imagine a cross-border marketplace processing 50,000 transactions a week. They started with just Stripe. Then they expanded to Europe and Southeast Asia. Suddenly, 3D Secure 2.0 friction is killing conversion in Germany. PayPal is preferred in Italy. A local Brazilian acquirer offers better rates for Boleto.

Your engineers are now juggling four different SDKs, maintaining four different webhook parsers, and manually implementing fallback logic: "If Stripe fails, try Adyen; if Adyen times out, try PayPal." It's a maintenance nightmare. They need a unified config. They need routing rules that determine which gateway to use for each transaction, taking into account currency, amount, and card type ^[6].

They need a routing-validator.sh to catch config drift before it hits production. They need a gateway-adapter.ts that standardizes createPaymentIntent and confirmPayment across providers. This is exactly what the pack solves. When you scaffold the project with scaffold-orchestrator.sh, you get the structure: requirements gathering, gateway selection, architecture design, SDK integration, orchestration logic, and compliance validation. You don't have to guess the phases; the skill.md guides the agent through the entire workflow.

The examples/worked-example-orchestration.yaml shows a real-world flow for a US Credit Card transaction with 3D Secure, including fallback to PayPal and retry logic. You see how the config drives behavior. You see how the orchestrator handles the state machine. You stop writing spaghetti code and start writing declarative routing rules.

Declarative Routing, Pluggable Adapters, and CI-Enforced Compliance

Once you install this skill, your checkout code changes. You stop writing vendor-specific logic. You write to the orchestrator interface. Your orchestration-config.yaml becomes the single source of truth for routing, fallbacks, and retry logic. The routing-validator.sh script runs in CI; if your routing strategy is invalid or fields are missing, the build breaks. You get pluggable adapters via gateway-adapter.ts. You can add a new gateway by implementing the interface, not by hacking the core.

You get compliance references baked in—PCI DSS, GDPR, PSD2—so your security reviews are faster. You can monitor performance across gateways and support smart routing with data analysts ^[7]. For dynamic pricing engines, accurate payment routing ensures that price calculations aren't distorted by failed transactions or currency conversion errors, making dynamic pricing reliable. You can also integrate with product recommendation AI to suggest payment methods based on user history, or sync with real-time inventory to hold stock only after a successful orchestration step. And when you need to seller onboarding in a marketplace, the orchestrator ensures payouts are routed correctly based on the seller's region and preferred processor.

The examples/stripe-ios-integration.swift file gives you production-grade Swift code for integrating Stripe as a gateway in an iOS app. It covers FlowController, PaymentSheet, EmbeddedCheckout, and error handling patterns. You don't have to reverse-engineer the Apple Pay flow. You get the code. You drop it in. You ship.

What's in the Payment Orchestration Pack

• skill.md — Orchestrator skill file defining the Payment Orchestration workflow, referencing all templates, references, scripts, and examples. Guides the agent through requirements, gateway selection, architecture, SDK integration, orchestration logic, and compliance.
• references/payment-orchestration-core.md — Canonical knowledge on payment orchestration concepts, architecture patterns, routing strategies, idempotency, and connector management. Includes excerpts on Hyperswitch-style switches, ISO 20022 standards, and best practices.
• references/compliance-and-security.md — Reference for PCI DSS requirements, data minimization, tokenization, regional compliance (GDPR, PSD2), and security best practices for payment orchestration systems.
• templates/orchestration-config.yaml — Production-grade configuration template for a payment orchestrator/router. Defines connectors, routing rules, fallback strategies, retry logic, and metadata. Used to generate or validate orchestration behavior.
• templates/gateway-adapter.ts — TypeScript interface and implementation pattern for a payment gateway adapter. Standardizes methods like createPaymentIntent, confirmPayment, refund, and status checks to enable pluggable gateway integration.
• scripts/scaffold-orchestrator.sh — Executable script to scaffold a payment orchestration project structure, generate config files, create mock server stubs, and initialize a git repository. Ensures consistent project setup.
• validators/routing-validator.sh — Validator script that checks orchestration-config.yaml for valid routing strategies, required fields, and logical consistency. Exits non-zero on failure to enforce configuration correctness.
• examples/worked-example-orchestration.yaml — Worked example of a complete orchestration flow for a US Credit Card transaction with 3D Secure, including fallback to PayPal and retry logic. Demonstrates real-world usage of the config template.
• examples/stripe-ios-integration.swift — Swift code examples based on Context7 docs for integrating Stripe as a gateway in an iOS app. Includes FlowController, PaymentSheet, EmbeddedCheckout, and error handling patterns.

Install the Pack and Ship

Stop hardcoding gateways. Start shipping with a resilient, compliant, and router-friendly checkout architecture. Upgrade to Pro to install the Payment Orchestration Pack.