--- name: payment-integration category: specialized-domains description: Use when implementing payment systems, integrating payment gateways, or handling financial transactions that require PCI compliance, fraud prevention, and secure transaction processing. codex-short-description: "Integrate payment gateways with PCI compliance and fraud prevention" allowed-tools: - Read - Write - Edit - Bash - Glob - Grep loop-eligible: false compatibility: claude-code codex opencode --- # Payment Integration You connect an application to systems that move money, where the interesting cases are the ones that fail halfway. ## Card data should never reach your servers Tokenize at the client with the processor's hosted fields or SDK, and store the token. The moment raw card numbers touch your infrastructure, that infrastructure is in PCI scope — logging, backups, error reports, and everything downstream of them. The cheapest compliance posture is the one where you have nothing to protect. Verify this by checking what actually gets logged, since the leak is almost always an error handler or a request dump rather than the intended path. ## Authorization and capture are separate decisions Authorize to reserve funds, capture when you have delivered or shipped. Conflating them means refunding rather than voiding when the order fails, which costs fees and shows on the customer's statement. Know the authorization expiry window — a hold that lapses before capture leaves you with an order you cannot collect on. ## A timeout is not a decline If the gateway does not answer, the transaction may still have succeeded. Never retry blindly into that ambiguity: send an idempotency key with every attempt so a retry is safe, and resolve unknowns by querying the processor for the transaction's real state. Treating a timeout as failure is how customers get charged for orders that were never created. ## Webhooks are the real source of truth, and they are hostile input Most state changes — settlement, chargeback, dispute, subscription renewal, delayed decline — arrive asynchronously. Verify the signature on every webhook, handle duplicates and out-of-order delivery idempotently, return 200 quickly and process off the request path, and reconcile against the processor's API rather than trusting the payload alone. A webhook endpoint that trusts its body is an endpoint anyone can use to mark orders paid. ## Fraud controls trade false positives for losses, and that is a business decision Present the trade rather than picking silently: a rule tuned to catch more fraud declines more legitimate customers. Use the signals the processor already provides (AVS, CVV, 3-D Secure, network risk scores) before building anything bespoke, and route liability deliberately — 3-D Secure shifts chargeback liability, which is frequently worth more than the conversion it costs. ## Money bugs are found by reconciliation, not by tests Reconcile your records against processor settlement daily, including fees, refunds, and chargebacks, and make unmatched items someone's job. Amounts are integer minor units with an explicit currency, never floats. Currency conversion happens at a recorded rate, at a recorded time. ## Reporting State where card data flows and what is in PCI scope, the auth/capture model, the idempotency and timeout-resolution strategy, which webhooks are consumed and how they are verified, the fraud controls and the false-positive trade they imply, and how reconciliation runs. ## Self-Evolve Loop Journal: `~/.ink-and-agency/learnings/payment-integration.md` (workspace-local `.ink-and-agency/learnings/payment-integration.md` where the sandbox confines writes). Read it first, append what the run taught last — [SELF-EVOLVE.md](../SELF-EVOLVE.md).