Payment Authentication with 3DS and SCA

Pathrule4 Rules • 2 Memories • 1 Skill

Card authentication can add issuer challenges, redirects, app switches, browser returns, exemptions, asynchronous authorization, and region-specific requirements between payment creation and a final charge outcome. This pattern constrains server authority, return handling, amount identity, and fulfillment; it records authentication and recovery states and supplies a complete challenge-flow verification procedure. It differs from user login and OAuth because the authenticated subject is a cardholder for one payment attempt, and the final authority remains the payment provider and issuer network.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

test-3ds-sca-payment-flow

src/

payments/

Treat provider payment state as the final authority

Reuse one logical payment attempt through authentication

Request exemptions without depending on them

Authentication evidence belongs to provider records

checkout/

Keep return destinations fixed and state opaque

Authentication and authorization are separate payment states

Rules

Treat provider payment state as the final authority/src/paymentshighstrictVerify authenticated server-side state and amount before marking an order payable or fulfilled.

1	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.
2
3	- Create and confirm payment attempts through authenticated server calls and bind them to the server-owned order, amount, and currency.
4	- On return, load the checkout by opaque identity and retrieve current payment state from the server or verified provider event.
5	- Require the provider identity, account, amount, currency, and terminal state to match the order before advancing it.
6	- Trigger fulfillment after the paid transition commits through durable work, never directly from client JavaScript.
7
8	See /src/checkout for the adjacent decision or procedure that completes this constraint.

Reuse one logical payment attempt through authentication/src/paymentshighstrictPreserve order and payment identities across redirects, challenges, reloads, and retries instead of creating a replacement automatically.

1	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.
2
3	- Generate a stable checkout and provider idempotency identity before the first confirmation request.
4	- Store the provider payment reference and required next-action state against the order before returning control to the browser.
5	- Return to the same server checkout identity and query current status after refresh, browser back, repeated callback, or delayed completion.
6	- Create a new payment attempt only after the prior one is terminal or explicitly cancelled and record the relationship between attempts.
7
8	See /tests/payments for the adjacent decision or procedure that completes this constraint.

Keep return destinations fixed and state opaque/src/checkouthighstrictUse allowlisted application return routes and opaque checkout references instead of forwarding arbitrary URLs or financial state through the browser.

1	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.
2
3	- Construct return URLs from server configuration and a small route allowlist; do not accept a full return URL from the browser.
4	- Carry only an opaque checkout or continuation reference and recover customer, order, amount, and provider identity from server storage.
5	- Expire continuation references according to payment lifetime and require the current user or guest secret to own the checkout.
6	- 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.
7
8	See /src/payments for the adjacent decision or procedure that completes this constraint.

Request exemptions without depending on them/src/paymentsmediumstrictProvide accurate risk and transaction context, but keep every flow capable of handling an issuer-requested challenge.

1	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.
2
3	- Send truthful customer, transaction, and recurring-payment context through supported provider fields; do not misclassify a payment merely to avoid challenge.
4	- Model authentication-required as a normal recoverable state on every eligible card flow.
5	- Keep off-session and recurring agreements tied to the provider's mandate or credential framework and handle authentication-required recovery with the customer.
6	- Measure challenge, abandonment, exemption, authorization, and recovery outcomes by market without logging prohibited card or authentication data.
7
8	See /src/checkout for the adjacent decision or procedure that completes this constraint.

Memories

Authentication and authorization are separate payment states/src/checkoutRepresent challenge progress separately from whether funds were authorized, captured, failed, cancelled, or require later action.

1	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.
2
3	- Model pending authentication, action required, processing, authorized, captured, failed, cancelled, and ambiguous outcomes with allowed transitions.
4	- Display instructions from server-owned state and provider-safe client data, then refresh authoritative status after any action.
5	- Do not reserve inventory or services indefinitely while authentication is abandoned; use an expiry and resume policy tied to the checkout.
6	- Keep order and fulfillment state separate from the payment attempt so a replacement attempt can pay the same order without duplicating it.
7
8	See /src/payments for the rule or workflow that puts this decision into practice.

Authentication evidence belongs to provider records/src/paymentsStore references and outcome fields needed for support and compliance without retaining sensitive challenge payloads or card authentication secrets.

1	Payment providers and issuers hold the detailed authentication exchange. Application storage usually needs attribution and outcome, not raw protocol messages or browser challenge content.
2
3	- Store provider payment and authentication references, outcome category, timestamps, amount, currency, and order relationship needed for reconciliation.
4	- Do not log or persist raw card numbers, cryptograms, challenge frames, secret client values, or full provider payloads by default.
5	- Restrict access to payment-authentication evidence and define retention from support, dispute, and legal requirements.
6	- Use provider dashboards or APIs for detailed investigation and correlate through stable references rather than copying sensitive data into general observability.
7
8	See /tests/payments for the rule or workflow that puts this decision into practice.

Skills

test-3ds-sca-payment-flow/rootExercise frictionless, challenged, abandoned, delayed, failed, repeated, and asynchronous payment authentication outcomes.

1	---
2	name: test-3ds-sca-payment-flow
3	description: Verify a 3DS, SCA, or card-authentication change before production rollout.
4	---
5
6	# Test 3ds Sca Payment Flow
7
8	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.
9
10	1. Test frictionless approval, issuer challenge, challenge failure, authorization decline, processing delay, cancellation, timeout, and unsupported client conditions.
11	2. Refresh, close, reopen, use browser back, repeat the return route, and complete authentication in another tab while preserving one order and attempt.
12	3. Replay duplicate and out-of-order provider events and compare return-page status with authoritative server status.
13	4. Attempt wrong user, expired continuation, modified amount, modified currency, wrong provider account, and arbitrary return destination inputs.
14	5. Verify inventory expiry, customer recovery, replacement payment attempt, final fulfillment, and reconciliation for every terminal and ambiguous outcome.
15
16	## Exit criteria
17
18	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.

Why this pattern

AI agents often mark payment complete on the return URL, create a new attempt after a challenge reload, or lose the order when the customer completes authentication asynchronously.

Built for Payment teams accepting cards where issuer authentication or strong customer authentication may be required.

Keeps your assistant from:

Fulfilling from an untrusted success redirect
Creating duplicate payment attempts during challenge recovery
Charging an amount different from the authenticated attempt
Leaving customers stuck after completing authentication on another page or app

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25