3ds-test-flow-reference

Overview

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.

When to use

• Designing test coverage for a payment integration handling 3DS.
• Auditing existing 3DS flow implementation.
• Investigating "customer says 3DS challenge looked broken" reports.
• PR review of payment-redirect flows.

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 references/gateway-test-cards.md. 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 payment-flow-states-reference
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.

References

• 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).
• Companion catalogs: payment-flow-states-reference, pci-dss-scope-reference.
• Consumed by: stripe-test-cards-and-webhooks, adyen-test-mode, braintree-test-cards.