3-D Secure (3DS) test flows

3-D Secure (3DS) is the EMVCo-specified card-authentication protocol. Per emvco.com (opens in new window), 3DS 2.x is the current spec (cite by stable ID: EMV 3-D Secure Protocol Specification v2.x); 3DS 1.0 is deprecated.

Use this reference when designing multi-gateway 3DS test coverage, auditing a 3DS redirect round-trip, or investigating a challenge-flow regression that is not gateway-specific.

The three flow outcomes

Per EMVCo 3DS 2.x spec:

The merchant's job: send all available data to the gateway; the gateway + issuer + 3DS server decide the flow.

SCA under PSD2

Per European Banking Authority RTS on SCA (opens in new window): since September 2019 (enforcement gradual through 2021), EU card payments require two-factor SCA (two of knowledge / possession / inherence). Exemptions: low-value (< €30), recurring, trusted-beneficiary, merchant-initiated - each with tracking requirements.

Per-gateway test cards

Per-PAN 3DS test cards for Stripe, Adyen, and Braintree, each with its source doc, are in gateway-test-cards.md (opens in new window). The core Stripe cards used in the assertions below: 4000 0000 0000 3055 (frictionless) and 4000 0027 6000 3184 (challenge).

Test flow surface

1. Merchant calls Authorize / PaymentIntent / Charge
2. Gateway returns "requires_action" / "RedirectShopper" / "PAYER_ACTION_REQUIRED"
   per the host SKILL.md state grid
3. Frontend redirects user to issuer-hosted 3DS challenge
4. User completes challenge (or auto-completes for frictionless)
5. Redirect back to merchant return URL
6. Merchant confirms PaymentIntent (or equivalent)
7. Gateway returns final state (succeeded / failed)

Test surface per step:

Frictionless vs challenge - testable assertions

test('frictionless authentication', async () => {
  // Card 4000 0000 0000 3055 in Stripe test mode
  const intent = await stripe.paymentIntents.create({
    amount: 1000, currency: 'eur',
    payment_method: 'pm_card_threeDSecure2Supported',
    confirm: true,
  });
  expect(intent.status).toBe('succeeded');  // No challenge needed
});

test('challenge flow', async () => {
  // Card 4000 0027 6000 3184
  const intent = await stripe.paymentIntents.create({
    amount: 1000, currency: 'eur',
    payment_method: 'pm_card_threeDSecure2Required',
    confirm: true,
    return_url: 'https://example.com/return',
  });
  expect(intent.status).toBe('requires_action');
  expect(intent.next_action.type).toBe('redirect_to_url');
});

Anti-patterns

Limitations

• EMVCo 3DS spec is paywalled. Reference by stable ID; rely on gateway docs for test cards.
• Issuer-hosted challenge UIs vary. Bank-specific design; test via e2e against gateway test mode.
• SCA exemptions are policy + technical. Code must claim the right exemption + log the decision.
• 3DS data fields are extensive. Each gateway has its own field names; per-gateway docs are authoritative.

Sources

• EMVCo 3-D Secure (paywalled; cite by stable ID): emvco.com/specifications/ (opens in new window).
• Stripe 3DS test cards: docs.stripe.com/testing#regulatory-cards (opens in new window).
• Adyen 3DS test cards: docs.adyen.com/development-resources/test-cards-and-credentials/test-card-numbers (opens in new window).
• Braintree 3DS testing: developer.paypal.com/braintree/docs/guides/3d-secure/testing/node (opens in new window).
• EBA RTS on SCA: eba.europa.eu/regulation-and-policy/payment-services-and-electronic-money/regulatory-technical-standards-on-strong-customer-authentication-and-secure-communication-under-psd2 (opens in new window).

Gateway 3DS test cards

Per-PAN test cards that drive 3DS challenge, frictionless, and bypass flows in each gateway's test mode. Cross-referenced from 3ds-flows.md (opens in new window). For single-gateway work, prefer the gateway skills (stripe-test-cards-and-webhooks, payment-gateway-sandboxes).

Stripe

Per docs.stripe.com/testing#regulatory-cards (opens in new window):

Adyen

Per docs.adyen.com/development-resources/test-cards-and-credentials/test-card-numbers (opens in new window):

Braintree

Per developer.paypal.com/braintree/docs/guides/3d-secure/testing/node (opens in new window):

Per-platform payment state machines

Deep reference for payment-flow-states-reference SKILL.md. Consult when mapping the canonical lifecycle onto a specific provider, or when auditing that a state-handling integration covers every provider-specific state. The canonical-state names and the decision workflow stay in the SKILL; the full per-platform terminology grid, the per-provider state machines, and the async webhook / refund / dispute detail live here.

Per-platform terminology mapping

Every provider names the same lifecycle differently. This grid maps each canonical state to its provider-specific value.

Per-platform state machines

Each provider exposes one primary object whose status field walks the lifecycle. Auth-only flows stop at the authorized state until an explicit capture; auth+capture flows run straight to the captured state.

• Stripe - PaymentIntent.status. requires_payment_method -> requires_action (if 3DS) -> processing -> succeeded. With capture_method=manual the intent stops at requires_capture until a capture call. Terminal off-path states: canceled; a declined charge is failed. Per docs.stripe.com/payments/payment-intents (opens in new window).
• Adyen - Authorisation then Capture. Received -> RedirectShopper (if 3DS) -> Pending -> Authorised, then a separate [Capture] event reaches Settled. Off-path: Refused, Cancelled, [Refund] Settled, [Chargeback]. Per docs.adyen.com/online-payments/build-your-integration/payment-result-codes (opens in new window).
• PayPal - Orders v2. CREATED -> PAYER_ACTION_REQUIRED (approval) -> APPROVED -> capture -> COMPLETED. Off-path: DECLINED, VOIDED, REFUNDED, plus a dispute resource. Per developer.paypal.com/docs/api/orders/v2/ (opens in new window).
• Braintree - Transaction status. created -> submitted_for_settlement -> settled. Auth-only stops at authorized. Off-path: gateway_rejected / failed, voided, refunded, disputed. Per developer.paypal.com/braintree/docs/reference/general/statuses (opens in new window).

Webhook event sequence

Providers emit one webhook per state transition; the async arrival is why tests must wait for the webhook, not the synchronous API return. Stripe example:

1. customer.created
2. payment_intent.created
3. payment_intent.requires_action   (if 3DS)
4. payment_intent.processing
5. payment_intent.succeeded
   AND
   charge.succeeded

Refund states

captured payment
   ↓
   refund created (status: pending)
   ↓
   refund succeeded (or failed)

Refunds are async: the API call returns immediately with pending, then a webhook delivers the final state minutes to hours later. Per docs.stripe.com/refunds (opens in new window).

Dispute / chargeback states

The most-complex part of the state machine. Per Visa's chargeback reason codes (cite by stable ID: Visa Chargeback Reason Codes), the customer's bank initiates the chargeback and the merchant has a fixed window to respond.

Disputes resolve over weeks; test scenarios use test-mode dispute APIs to trigger the transitions synchronously. Per docs.stripe.com/disputes (opens in new window).