Introduction

Testing Payer Authentication (3-D Secure, or 3DS) is essential to ensure your integration handles all possible authentication flows: frictionless, step-up (challenge), error, exemption, and data-only scenarios. This guide provides prerequisites, test card numbers, expected API responses, ECI mappings, and actions for each scenario.

General Testing Guidelines

• Test all scenarios for each supported card type.
• Use the provided test card numbers and set expiration date:
  • 3DS 2.x: January of current year + 3 (e.g., if now is 2025, use January 2028).
  • Other tests: December of current year + 3.
• Remove spaces from card numbers.
• Always include all required API fields for the transaction/order.

Key API Response Fields

Enrollment Check Response

Authentication Validation Response

Test Scenarios and Expected Actions

1. Frictionless Authentication Is Successful

• Expected: Status = AUTHENTICATION_SUCCESSFUL, VERes enrolled = Y, PARes status = Y, CAVV/AVV/XID values present as applicable.
• Action: Use returned authentication values in authorization.

2. Frictionless Authentication Is Unsuccessful

• Expected: Status = AUTHENTICATION_FAILED, VERes enrolled = Y, PARes status = N.
• Action: Do not authorize; request alternate payment.

3. Stand-In Frictionless Authentication Attempted

• Expected: Status = AUTHENTICATION_SUCCESSFUL, VERes enrolled = Y, PARes status = A.
• Action: Add CAVV/ECI to authorization if needed.

4. Frictionless Authentication Is Unavailable

• Expected: Status = AUTHENTICATION_SUCCESSFUL, VERes enrolled = Y, PARes status = U.
• Action: Submit for authorization; no liability shift.

5. Frictionless Authentication Is Rejected

• Expected: Status = AUTHENTICATION_FAILED, VERes enrolled = Y, PARes status = R.
• Action: Do not authorize; request alternate payment.

6. Authentication Is Not Available

• Expected: Status = AUTHENTICATION_SUCCESSFUL, VERes enrolled = U, directoryServerErrorCode: 101.
• Action: Submit for authorization as unauthenticated; no liability shift.

7. Check Enrollment Error

• Expected: Status = AUTHENTICATION_SUCCESSFUL, VERes enrolled = U, directoryServerErrorCode: 101.
• Action: Submit for authorization and contact support; no liability shift.

8. Time Out

• Expected: Status = AUTHENTICATION_SUCCESSFUL, VERes enrolled = U, directoryServerErrorCode: 402.
• Action: After 10–12 seconds, proceed with authorization; no liability shift.

9. Step-Up Authentication Is Successful

• Check Enrollment: Status = PENDING_AUTHENTICATION, VERes enrolled = Y, PARes status = C, XID = <XID value>.
• Validation Authentication: Status = AUTHENTICATION_SUCCESSFUL, PARes status = Y, XID = <XID value>, CAVV = <CAVV value>.
• Action: Add CAVV and ECI to authorization if separate.

10. Step-Up Authentication Is Unsuccessful

• Check Enrollment: Status = PENDING_AUTHENTICATION, VERes enrolled = Y, PARes status = C, PAReq and ACS URL present.
• Validation Authentication: Status = AUTHENTICATION_FAILED, PARes status = N, XID = <XID value> (Amex only).
• Action: Do not authorize; request alternate payment.

11. Step-Up Authentication Is Unavailable

• Check Enrollment: Status = PENDING_AUTHENTICATION, VERes enrolled = Y, PARes status = C.
• Validation Authentication: Status = AUTHENTICATION_SUCCESSFUL, PARes status = U, XID = <XID value>.
• Action: Retry authentication, or process without liability shift.

12. Error During Authentication

• Check Enrollment: Status = PENDING_AUTHENTICATION, VERes enrolled = Y, PARes status = C, PAReq present.
• Action: Retry or process without authentication as appropriate.

13. Authentication Is Bypassed

• Check Enrollment: Status = AUTHENTICATION_SUCCESSFUL, VERes enrolled = B, XID = <XID value>.
• Action: Submit for authorization. No liability shift.

Special and Additional Test Cases

Require Method URL (Device Data Collection)

• Card: Visa 4000100000000000
• Result: VERes enrolled = Y, PARes status = Y, CAVV = <CAVV value>, ECI = 07
• Action: Wait at least 7–10 seconds for device data collection. Success = frictionless; failure = PARes status C.

Recurring/3RI and Exemption Scenarios

• First Recurring Transaction: Fixed Amount
  Card: Mastercard 52000000002805
  Required Fields: Message category = 01, Device channel = APP(01)/BROWSER(02), Three RI Indicator = 01, Challenge code = 03, Authentication code = 02, Purchase date, frequency, end date
  Result: Check Enrollment: Status = PENDING_AUTHENTICATION, VERes enrolled = Y, PARes status = C. Validation: Status = AUTHENTICATION_SUCCESSFUL, PARes status = Y, ECI = 07
• TRA Exemption (Low Value): Mastercard, Visa, Discover, Cartes Bancaires
  Cards: Mastercard: 52000000001161 (2.1.0), 52000000002052 (2.2.0); Visa: 40000000002024; Discover: 60110000001002; CB Visa: 40000000003006; CB Mastercard: 52000000003001
  Check Enrollment Result: Mastercard 2.1.0: PARes status = N, ECI = 06; Mastercard 2.2.0: PARes status = I, ECI = 06; Visa: PARes status = I, ECI = 07; Discover: PARes status = Y, ECI = 05; CB: PARes status = Y, ECI = (none)
  Action: Proceed to authorization.
• Trusted Beneficiary (Whitelist) Scenarios
  Cards: Visa: 40000000002008; Mastercard: 52000000002003
  Required Field: Challenge code (09 for prompt, 08 for pre-whitelisted)
  Check Enrollment: PARes status = C (prompt), Y (pre-whitelisted); CAVV as available, ECI (Visa = 05, Mastercard = 02)
  Action: Append CAVV and ECI to authorization.

Data Only Authentication

• Visa Data Only: Card: 40000000002024; ChallengeIndicator: 06; PAResStatus: I, ECI = 07; Action: Append ECI and Directory Server transaction ID to authorization.
• Mastercard Data Only: Card: 52000000001005; Message Category: 80, ScoreRequest: Y; PAResStatus: U, ECI = 04; Action: Append ECI and Directory Server transaction ID to authorization.

E-Commerce Indicator (ECI) Value Reference

The electronic commerce indicator is used in payer authentication to indicate the level of security used when the cardholder provided payment information to the merchant. Its value corresponds to the authentication result and the characteristics of the merchant checkout process. Each card network, e.g., Visa, Mastercard, JCB, has specific rules around the appropriate values and use of the ECI.

Common HTTP Status Codes

Additional Notes

• Mada: Merchant country must be SA (or use CountryCodeOverride: SA).
• Meeza: Test like Mastercard with card type 067.
• Mastercard: Always include 3DS version and directory server transaction ID in authorization.
• All scenarios: Always include minimum required order fields and recommended API best practices.

Test Card Numbers

Additional Resources

For more information and comprehensive technical guidance on the use of Payer Authentication, refer to the Payer Authentication User Guide in our Developer Center.