# Pathrule Pattern: Payment Authentication with 3DS and SCA (1.0.0) # ::pathrule:package:payment-3ds-sca ### [RULE] Treat provider payment state as the final authority (path: /src/payments) Browser callbacks and return parameters are navigation hints. They can be replayed, forged, reached before provider processing finishes, or omitted when the customer closes the page. - Create and confirm payment attempts through authenticated server calls and bind them to the server-owned order, amount, and currency. - On return, load the checkout by opaque identity and retrieve current payment state from the server or verified provider event. - Require the provider identity, account, amount, currency, and terminal state to match the order before advancing it. - Trigger fulfillment after the paid transition commits through durable work, never directly from client JavaScript. See /src/checkout for the adjacent decision or procedure that completes this constraint. --- ### [RULE] Reuse one logical payment attempt through authentication (path: /src/payments) An authentication-required result is an intermediate state, not a failed checkout. Creating another payment attempt can produce multiple authorizations and make later events impossible to reconcile. - Generate a stable checkout and provider idempotency identity before the first confirmation request. - Store the provider payment reference and required next-action state against the order before returning control to the browser. - Return to the same server checkout identity and query current status after refresh, browser back, repeated callback, or delayed completion. - Create a new payment attempt only after the prior one is terminal or explicitly cancelled and record the relationship between attempts. See /tests/payments for the adjacent decision or procedure that completes this constraint. --- ### [RULE] Keep return destinations fixed and state opaque (path: /src/checkout) Challenge flows leave the application and later return through user-controlled navigation. An open redirect or trusted amount in query parameters turns authentication plumbing into a phishing or payment-integrity weakness. - Construct return URLs from server configuration and a small route allowlist; do not accept a full return URL from the browser. - Carry only an opaque checkout or continuation reference and recover customer, order, amount, and provider identity from server storage. - Expire continuation references according to payment lifetime and require the current user or guest secret to own the checkout. - Make the return handler safe to call repeatedly and prevent it from performing the charge, creating an order, or trusting success text from the issuer page. See /src/payments for the adjacent decision or procedure that completes this constraint. --- ### [RULE] Request exemptions without depending on them (path: /src/payments) An exemption or frictionless preference is not a guarantee. The issuer or provider can still require authentication based on regulation, risk, card, amount, or account state. - Send truthful customer, transaction, and recurring-payment context through supported provider fields; do not misclassify a payment merely to avoid challenge. - Model authentication-required as a normal recoverable state on every eligible card flow. - Keep off-session and recurring agreements tied to the provider's mandate or credential framework and handle authentication-required recovery with the customer. - Measure challenge, abandonment, exemption, authorization, and recovery outcomes by market without logging prohibited card or authentication data. See /src/checkout for the adjacent decision or procedure that completes this constraint. --- ### [MEMORY] Authentication and authorization are separate payment states (path: /src/checkout) A cardholder can complete authentication and still have authorization declined, while an authorization can require capture or later confirmation. One boolean cannot describe the state machine. - Model pending authentication, action required, processing, authorized, captured, failed, cancelled, and ambiguous outcomes with allowed transitions. - Display instructions from server-owned state and provider-safe client data, then refresh authoritative status after any action. - Do not reserve inventory or services indefinitely while authentication is abandoned; use an expiry and resume policy tied to the checkout. - Keep order and fulfillment state separate from the payment attempt so a replacement attempt can pay the same order without duplicating it. See /src/payments for the rule or workflow that puts this decision into practice. --- ### [MEMORY] Authentication evidence belongs to provider records (path: /src/payments) Payment providers and issuers hold the detailed authentication exchange. Application storage usually needs attribution and outcome, not raw protocol messages or browser challenge content. - Store provider payment and authentication references, outcome category, timestamps, amount, currency, and order relationship needed for reconciliation. - Do not log or persist raw card numbers, cryptograms, challenge frames, secret client values, or full provider payloads by default. - Restrict access to payment-authentication evidence and define retention from support, dispute, and legal requirements. - Use provider dashboards or APIs for detailed investigation and correlate through stable references rather than copying sensitive data into general observability. See /tests/payments for the rule or workflow that puts this decision into practice. --- ### [SKILL] test-3ds-sca-payment-flow (path: /) --- name: test-3ds-sca-payment-flow description: Verify a 3DS, SCA, or card-authentication change before production rollout. --- # Test 3ds Sca Payment Flow Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result. 1. Test frictionless approval, issuer challenge, challenge failure, authorization decline, processing delay, cancellation, timeout, and unsupported client conditions. 2. Refresh, close, reopen, use browser back, repeat the return route, and complete authentication in another tab while preserving one order and attempt. 3. Replay duplicate and out-of-order provider events and compare return-page status with authoritative server status. 4. Attempt wrong user, expired continuation, modified amount, modified currency, wrong provider account, and arbitrary return destination inputs. 5. Verify inventory expiry, customer recovery, replacement payment attempt, final fulfillment, and reconciliation for every terminal and ambiguous outcome. ## Exit criteria The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.