3DS in P1

3DS overview

The 3D Secure (3DS) authentication system provides an additional security layer for card-not-present transactions through Strong Customer Authentication (SCA). The system supports both rules-based decisioning and multiple authentication methods to verify cardholder identity during online purchases.

Supported Networks:

Visa (Visa Secure)

Mastercard (Mastercard SecureCode®)

Authentication Standard: Strong Customer Authentication (SCA) compliant

Note: Both Mastercard and Visa support EMV® 3D Secure.

Quick reference

Authentication types

OTP (One-Time Password) is a temporary, single-use, secure code. The system sends it via SMS to the customer's mobile phone or email.

For OTP-based authentication, OTPSMS or OTPEMAIL, you must provide customer contact information as follows:

Mobile number: Retrieve this during card creation. It must be the customer’s verified mobile phone number. See the phoneNumber attribute in the Create new card API endpoint for the required format.

Email address: Retrieve this during card creation. It must be the customer’s verified email address. See the emailAddress attribute in the Create new card API endpoint for the required format.

Type	Description	Validation Required	Use Case
OTPSMS	SMS OTP	❌ No (automatic)	Standard e-commerce
OTPEMAIL	Email OTP	❌ No (automatic)	Standard e-commerce
OUTOFBANDOTHER	Biometric (OOB)	✅ Yes (manual)	Mobile app with biometrics

API endpoints summary

Endpoint	Method	Purpose
/v1/3ds/{id}	GET	Get authentication details
/v1/3ds/{id}/validate	POST	Validate OOB authentication (OUTOFBANDOTHER only)
/v1/simulate/3ds/authenticate	POST	Simulate 3DS authentication (testing)

Important notes

Authentication flow:

sequenceDiagram
      participant Merchant
      participant P1 as Cross River P1
      participant Partner
      participant Cardholder

      Note over Merchant,Cardholder: 3DS Authentication Flow

      Merchant->>P1: 1. Initiate 3DS authentication request
      P1->>P1: 2. Evaluate authentication rules

      alt Approve
          P1->>Merchant: Transaction Approved
      else Decline
          P1--xMerchant: Transaction Declined
      else Challenge Required
          P1->>Partner: 3. Send authentication webhook<br/>(based on authentication type)
          Note over Partner,Cardholder: Partner Configuration Applied
          Partner->>Cardholder: 4. Partner uses webhook from Cross River<br/>to present authentication options
          Cardholder->>Cardholder: 5. Complete authentication
          Cardholder->>Partner: 6. Authentication result
          Partner->>P1: 7. Return authentication response
          P1->>Merchant: 8. Final transaction result
      end

Merchant initiates 3DS authentication request

Cross River P1 evaluates rules (Approve/Decline/Challenge)

If challenge triggered, Cross River P1 sends webhook to partner (based on authentication type)

Cardholder presented with configured authentication options

Authentication method executes based on partner configuration

Validation requirements:

OUTOFBANDOTHER requires validation: After biometric authentication completes, merchant must call POST /v1/3ds/{id}/validate to send result back to P1

OTPSMS and OTPEMAIL are automatic: No validation endpoint call required. VCAS handles OTP validation internally

Three-domain model

3DS authentication involves three separate domains:

Domain Type	Description
Acquirer (merchant)	Merchant's e-commerce platform Initiates authentication request Receives authentication results
Issuer (Cross River P1)	Access Control Server (ACS) Processes authentication requests Sends authentication challenges
Interoperability (VCAS)	VCAS (Visa Card Authentication Service) Routes messages between domains Validates authentication results Handles both Visa and Mastercard authentication flows Generates CAVV tokens

Authentication methods

Method 1: Out of Band (OOB) authentication

Type: OUTOFBANDOTHER

Flow:

sequenceDiagram
      participant Merchant
      participant P1 as Cross River P1
      participant Partner
      participant Cardholder

      Note over Merchant,Cardholder: 3DS Authentication Flow - Challenge Required

      Merchant->>P1: 1. Initiate 3DS authentication request
      P1->>P1: 2. Evaluate authentication rules
      Note over P1: Challenge triggered
      P1->>Partner: 3. Send authentication webhook<br/>with authentication details
      Note over Partner: Partner uses webhook from Cross River
      Partner->>Cardholder: 4. Push notification to<br/>cardholder's mobile app
      Cardholder->>Cardholder: 5. Authenticate using biometrics<br/>(fingerprint, Face ID, etc.)
      Cardholder->>Partner: 6. Authentication completed
      Partner->>P1: 7. POST /v1/3ds/{id}/validate<br/>Send authentication result
      P1->>P1: 8. Process and confirm authentication<br/>(VCAS validation)
      P1->>Merchant: 9. Return final authentication result<br/>with CAVV and ECI
      Note over Merchant,P1: Result: Authentication successful<br/>Transaction approved

Merchant initiates 3DS authentication request

Cross River P1 evaluates authentication rules

If P1 triggers a challenge, P1 presents the cardholder with configured authentication options (based on partner configuration)

P1 initiates authentication webhook to partner with authentication details

Partner receives webhook and pushes notification to cardholder's mobile app

Cardholder authenticates using biometrics (fingerprint, Face ID, etc.) in the app

Partner sends authentication result to Cross River P1 via theValidate OUTOFBANDOTHER API endpoint.

P1 confirms authentication with VCAS (Visa Card Authentication Service)

P1 returns final authentication result with CAVV and ECI to merchant

Timeout: 10 minutes for cardholder response

Advantages:

Frictionless user experience

Biometric authentication

No manual code entry

Important: This method requires calling the /validate endpoint to send the authentication result back to P1.

Method 2: One-Time Passcode (OTP) authentication

SMS OTP

Type: OTPSMS

Flow:

sequenceDiagram
      participant Merchant
      participant P1 as Cross River P1
      participant Partner
      participant Cardholder

      Note over Merchant,Cardholder: 3DS Authentication Flow - OTP Challenge

      Merchant->>P1: 1. Initiate 3DS authentication request
      P1->>P1: 2. Evaluate authentication rules
      Note over P1: Challenge triggered
      P1->>Partner: 3. Send authentication webhook<br/>with OTP details
      Note over Partner: Partner uses webhook from Cross River
      Partner->>Cardholder: 4. Trigger OTP delivery via SMS<br/>to cardholder's phone
      Merchant->>Cardholder: 5. Display OTP entry screen
      Cardholder->>Merchant: 6. Enter OTP on<br/>merchant's validation screen
      Merchant->>P1: 7. Submit OTP for validation
      P1->>P1: 8. Validate OTP automatically<br/>(VCAS validation)
      P1->>Merchant: 9. Return authentication result<br/>with CAVV and ECI
      Note over Merchant,P1: Result: Authentication successful<br/>Transaction approved

Merchant initiates 3DS authentication request

Cross River P1 evaluates authentication rules

If P1 triggers a challenge, cardholder is presented with configured authentication options (based on partner configuration)

Cross River P1 initiates authentication webhook to partner with OTP details

Partner triggers OTP delivery via SMS to cardholder's phone

Merchant displays OTP entry screen to cardholder

Cardholder enters OTP on merchant's validation screen

VCAS validates OTP automatically (no /validate endpoint call needed)

Cross River P1 returns authentication result with CAVV and ECI

No validation endpoint required - OTP validation happens automatically within VCAS.

Important: Partner is responsible for sending the OTP via SMS based on details received in webhook.

Email OTP

Type: OTPEMAIL

Flow:

sequenceDiagram
      participant Merchant
      participant P1 as Cross River P1
      participant Partner
      participant Cardholder

      Note over Merchant,Cardholder: 3DS Authentication Flow - Email OTP Challenge

      Merchant->>P1: 1. Initiate 3DS authentication request
      P1->>P1: 2. Evaluate authentication rules
      Note over P1: Challenge triggered
      P1->>Partner: 3. Send authentication webhook<br/>with OTP details
      Note over Partner: Partner uses webhook from Cross River
      Partner->>Cardholder: 4. Trigger OTP delivery via email<br/>to cardholder's email address
      Merchant->>Cardholder: 5. Display OTP entry screen
      Cardholder->>Merchant: 6. Enter OTP on<br/>merchant's validation screen
      Merchant->>P1: 7. Submit OTP for validation
      P1->>P1: 8. Validate OTP automatically<br/>(VCAS validation)
      P1->>Merchant: 9. Return authentication result<br/>with CAVV and ECI
      Note over Merchant,P1: Result: Authentication successful<br/>Transaction approved

Merchant initiates 3DS authentication request

Cross River P1 evaluates authentication rules

If challenge is triggered, cardholder is presented with configured authentication options (based on partner configuration)

Cross River P1 initiates authentication webhook to partner with OTP details

Partner triggers OTP delivery via email to cardholder's email address

Merchant displays OTP entry screen to cardholder

Cardholder enters OTP on merchant's validation screen

VCAS validates OTP automatically (no /validate endpoint call needed)

Cross River P1 returns authentication result with CAVV and ECI

No validation endpoint required. OTP validation happens automatically within VCAS.

Important: Partner is responsible for sending the OTP via email based on details received in webhook.

OTP Validity: 10 minutes per code

Retry Logic	Resend Logic
Maximum 3 attempts to enter correct OTP Reference code displayed to confirm expected OTP Authentication fails after 3 incorrect attempts Important: PAN (Primary Account Number) remains active after failed attempts	Initial OTP sent automatically Up to 2 additional resends permitted (3 total OTPs maximum) Each resend generates a new OTP code Resend button becomes inactive after limit reached

Authentication rules system

Authentication rules provide a control layer for 3DS decisioning by allowing custom logic based on transaction attributes.

Purpose

Add custom decisioning logic to 3DS authentication flow

Works with both Cross River P1 decisioning and partner custom decisioning

Enforce stricter controls beyond base decisioning

Key limitation

Rules only enforce stricter controls or maintain existing declines. They cannot override declines.

Authentication decision flow

Step-by-step process

sequenceDiagram
      participant Merchant
      participant P1 as Cross River P1
      participant Partner
      participant Cardholder

      Note over Merchant,Cardholder: 3DS Authentication Flow

      Merchant->>P1: 1. Initiate 3DS authentication request
      P1->>P1: 2. Evaluate authentication rules

      alt Approve
          P1->>Merchant: Transaction Approved
      else Decline
          P1--xMerchant: Transaction Declined
      else Challenge Required
          P1->>Partner: 3. Send authentication webhook<br/>(based on authentication type)
          Note over Partner: Partner uses webhook from Cross River
          Partner->>Cardholder: 4. Present authentication options
          Cardholder->>Cardholder: 5. Complete authentication<br/>(method based on partner config)
          Cardholder->>Partner: 6. Authentication result
          Partner->>P1: 7. Return authentication response
          P1->>Merchant: 8. Final transaction result
      end

1. Merchant Initiates 3DS Authentication Request ↓ 2. P1 Receives Authentication Request ↓ 3. All Active Rules Evaluate Simultaneously ↓ 4. Each Rule Checks Transaction Attributes ↓ 5. Matching Rules Execute Actions (Approve/Decline/Challenge) ↓ 6. Apply "Most Restrictive" Decision Logic ↓ 7. If CHALLENGE triggered: ├─ P1 initiates authentication webhook to partner ├─ Cardholder presented with configured authentication options └─ Authentication method (OTPSMS/OTPEMAIL/OUTOFBANDOTHER) executes ↓ 8. Authentication Result ├─ For OTP methods: VCAS validates OTP automatically └─ For OOB methods: Partner calls /validate endpoint ↓ 9. P1 Confirms with VCAS (Visa Card Authentication Service) ↓ 10. Final Authentication Response (with CAVV and ECI) ↓ 11. Response Transmitted to Merchant

Decision logic - "most restrictive" principle

The system applies the strictest outcome among all matching rules:

Decision priority (most to least restrictive):

Decline: Transaction rejected immediately

Challenge: Additional verification required

Approve: Transaction proceeds (if no rules triggered)

Rules interaction

flowchart TD
    A[Transaction Received] --> B{Evaluate All Rules}
    B --> C{Any Rule Declines?}
    C -->|Yes| D[❌ Transaction Declined]
    D --> E[Cannot Be Overridden]
    C -->|No| F{Any Rule Triggers Challenge?}
    F -->|Yes| G{Another Rule Declines?}
    G -->|Yes| D
    G -->|No| H[⚠️ Challenge Flow Continues]
    F -->|No| I{Any Rules Match?}
    I -->|No| J[🔄 Default Decisioning Applies]
    I -->|Yes| K[✅ Process Matched Rules]

    style D fill:#f44336,color:#fff,stroke:#b71c1c
    style E fill:#f44336,color:#fff,stroke:#b71c1c
    style H fill:#ff9800,color:#fff,stroke:#e65100
    style J fill:#2196f3,color:#fff,stroke:#0d47a1
    style K fill:#4caf50,color:#fff,stroke:#1b5e20

If any rule declines → Transaction is declined (cannot be overridden)

If any rule triggers challenge → Challenge flow continues (unless another rule declines)

If no rules match → Default decisioning applies

Example scenario

Rules configured:

Rule A: Challenge when risk score > 600

Rule B: Decline when risk score > 800

Transaction with risk score 850:

Rule A matches → Action: Challenge

Rule B matches → Action: Decline

Result: Transaction DECLINED (decline is more restrictive than challenge)

Transaction with risk score 700:

Rule A matches → Action: Challenge

Rule B does NOT match

Result: Transaction CHALLENGED (cardholder must authenticate)

Available actions

Authentication rules can execute two actions:

1. Decline

Effect: Reject the transaction immediately

Use Case: High-risk transactions, blocked merchants, suspicious patterns

Result: Transaction fails 3DS authentication

2. Challenge

Effect: Trigger additional verification flow (OTP or OOB)

Use Case: Medium-risk transactions requiring cardholder verification

Result: Cardholder must authenticate to proceed

Authentication result codes

Success states

SUCCESS: Cardholder authenticated successfully

APPROVED: Authentication approved by issuer

Failure states

FAILURE: Authentication failed (incorrect OTP, biometric rejection)

TIMEOUT: Cardholder did not respond within 10 minutes

CHALLENGE_REQUIRED: Additional verification needed

DECLINED: Authentication declined by rules engine

Use cases

Use case 1: E-commerce purchase - low risk (frictionless)

Scenario: Customer purchases $50 item from known merchant

Flow:

sequenceDiagram
    participant Merchant
    participant P1 as Cross River 

    Merchant->>P1: 1. Initiate 3DS authentication request
    P1->>P1: 2. Evaluate rules<br/>Risk score: 450 (low)
    Note over P1: 3. No rules match<br/>No challenge triggered
    P1->>P1: 4. Approve authentication<br/>without cardholder interaction
    P1->>Merchant: 5. Return authentication result<br/>with CAVV and ECI
    Note over Merchant,P1: Result: Frictionless approval<br/>(no authentication challenge required)

Merchant initiates 3DS authentication request

P1 evaluates rules - Risk score: 450 (low)

No rules match - No challenge triggered

P1 approves authentication without cardholder interaction

P1 returns authentication result with CAVV and ECI

Result: Frictionless approval (no authentication challenge required)

Use case 2: E-commerce purchase - medium risk

Scenario: Customer purchases $500 item from new merchant

Flow:

sequenceDiagram
    participant Merchant
    participant P1 as Cross River 
    participant Partner
    participant Cardholder
    participant VCAS

    Merchant->>P1: 1. Initiate 3DS authentication request
    P1->>P1: 2. Evaluate rules<br/>Risk score: 650 (medium)
    Note over P1: 3. Rule matches:<br/>"Challenge when risk_score > 600"
    P1->>Partner: 4. Send authentication webhook<br/>with OTP details
    Partner->>Cardholder: 5. Present authentication options<br/>(SMS OTP, Email OTP)
    Cardholder->>Partner: 6. Select SMS OTP
    Partner->>Cardholder: 7. Send OTP via SMS<br/>to cardholder's phone
    Cardholder->>Merchant: 8. Enter correct OTP<br/>on merchant's screen
    Merchant->>VCAS: 9. VCAS validates OTP automatically
    VCAS->>P1: 10. Confirm authentication
    P1->>Merchant: 11. Return CAVV and ECI
    Note over Merchant,VCAS: Result: Authentication successful<br/>Transaction approved

Merchant initiates 3DS authentication request

Cross River P1 evaluates rules - Risk score: 650 (medium)

Rule matches: "Challenge when risk_score > 600"

Cross River P1 initiates authentication webhook to partner with OTP details

Cardholder presented with authentication options (SMS OTP, Email OTP)

Cardholder selects SMS OTP

Partner sends OTP via SMS to cardholder's phone (based on webhook data)

Cardholder enters correct OTP on merchant's screen

VCAS validates OTP automatically

Cross River P1 confirms with VCAS and returns CAVV

Result: Authentication successful, transaction approved

Use case 3: E-commerce purchase - high risk

Scenario: Customer purchases $1,000 item, cross-border transaction

Flow:

sequenceDiagram
    participant Merchant
    participant P1 as Cross River 

    Merchant->>P1: 1. Initiate 3DS authentication request
    P1->>P1: 2. Evaluate rules<br/>Risk score: 850 (high)
    Note over P1: 3. Rule matches:<br/>"Decline when risk_score > 800"
    P1->>P1: 4. Apply "Most Restrictive"<br/>decision logic
    P1--xMerchant: 5. Transaction declined
    Note over Merchant,P1: Result: Transaction declined immediately<br/>(no challenge triggered,<br/>no authentication required)

Merchant initiates 3DS authentication request

P1 evaluates rules - Risk score: 850 (high)

Rule matches: "Decline when risk_score > 800"

Apply "Most Restrictive" decision logic

Result: Transaction declined immediately (no challenge triggered, no authentication required)

Use case 4: OOB authentication (OUTOFBANDOTHER)

Scenario: Customer uses partner's mobile app with biometric support

Flow:

sequenceDiagram
      participant Customer as Customer<br/>(Cardholder)
      participant Merchant
      participant P1 as Cross River P1
      participant Partner

      Note over Customer,Partner: 3DS Authentication Flow - OOB Biometric

      Customer->>Merchant: 1. Initiate $300 purchase<br/>in mobile app
      Merchant->>P1: 2. Initiate 3DS authentication request
      P1->>P1: 3. Evaluate authentication rules<br/>Medium risk, challenge triggered
      P1->>Partner: 4. Send authentication webhook<br/>with OOB biometric details
      P1->>Merchant: 5. Return authenticationId<br/>and transactionId
      Note over Partner: Partner uses webhook from Cross River
      Partner->>Customer: 6. Send push notification<br/>to mobile device
      Customer->>Customer: 7. Authenticate with Face ID<br/>in partner's app
      Customer->>Partner: 8. Authentication completed
      Partner->>P1: 9. POST /v1/3ds/{id}/validate<br/>status: "SUCCESS"
      P1->>P1: 10. Confirm authentication<br/>(VCAS validation)
      P1->>Merchant: 11. Return CAVV and ECI
      Note over Customer,P1: Result: Frictionless authentication<br/>Transaction approved

Customer initiates $300 purchase in mobile app

Merchant initiates 3DS authentication request

P1 evaluates rules - Medium risk, challenge triggered

Cardholder presented with authentication options (partner configured for OOB biometric)

P1 initiates authentication webhook to partner

P1 returns authenticationId and transactionId to merchant

Partner receives webhook and sends push notification to customer's mobile device

Customer authenticates with Face ID in partner's app

Partner calls POST /v1/3ds/{id}/validate with status: "SUCCESS" to send result to P1

P1 confirms with VCAS and returns CAVV and ECI

Result: Frictionless authentication, transaction approved

3DS in P1

3DS overview

Quick reference

Authentication types

API endpoints summary

Important notes

Three-domain model

Acquirer (merchant)

Issuer (Cross River P1)

Interoperability (VCAS)

Authentication methods

Method 1: Out of Band (OOB) authentication

Method 2: One-Time Passcode (OTP) authentication

Authentication rules system

Purpose

Key limitation

Authentication decision flow

Step-by-step process

Decision logic - "most restrictive" principle

Decision priority (most to least restrictive):

Rules interaction

Example scenario

Available actions

1. Decline

2. Challenge

Authentication result codes

Success states

Failure states

Use cases

Use case 1: E-commerce purchase - low risk (frictionless)

Use case 2: E-commerce purchase - medium risk

Use case 3: E-commerce purchase - high risk

Use case 4: OOB authentication (OUTOFBANDOTHER)