3DS Integration Guide - Option 2

Overview

3D Secure (3DS) is an authentication protocol designed to provide an additional layer of security for online credit and debit card transactions. It helps prevent unauthorized card usage by requiring cardholders to authenticate themselves with their card issuer before completing a transaction.

3DS Authentication Modes

The 3DS authentication flow varies based on the card issuer's risk assessment. There are three possible outcomes:

1. Frictionless 3DS: Low-risk transactions are authenticated automatically without customer interaction. The system performs risk assessment via iframe, then directly completes the payment without requiring OTP.

2. Challenge 3DS: High-risk transactions require immediate customer verification. The customer is directly redirected to the ACS authentication page for OTP or biometric verification.

3. Mixed 3DS: The system first performs risk assessment via iframe. If additional verification is needed, the customer is then redirected to the ACS page for OTP verification.

Important for Integration: You cannot predict which mode will be used. The card issuer determines this based on real-time risk assessment. Your integration must dynamically handle all scenarios by checking the API response structure (next_action field) and webhook types.

Integration Steps

Integration Flow

The following diagram illustrates the 3DS authentication flow based on API response handling:

sequenceDiagram
    participant User
    participant Client as Merchant Client
    participant Server as Merchant Server
    participant UQPay as UQPay API
    participant ACS as Card Issuer ACS

    User->>Client: Click Checkout
    Client->>Server: Initiate Payment
    Server->>UQPay: Create Payment Intent (three_ds_action=enforce_3ds)
    UQPay-->>Server: Response (PI = REQUIRES_CUSTOMER_ACTION)
    
    Note over Server: Check next_action field
    
    alt next_action = redirect_to_url
        Note over Server,Client: Direct challenge required
        Server-->>Client: Send redirect URL
        Client->>ACS: Redirect to ACS Page
        User->>ACS: Enter OTP
        alt OTP Success
            ACS-->>Client: Redirect to return_url
            UQPay->>Server: Webhook (acquiring.payment_intent.succeeded)
        else OTP Failed
            ACS-->>Client: Redirect to Failure Page
            UQPay->>Server: Webhook (acquiring.payment_intent.failed)
        end
        
    else next_action = redirect_iframe
        Note over Server,Client: Risk assessment required
        Server-->>Client: Send iframe code
        Client->>Client: Embed and auto-submit iframe
        Client->>ACS: Submit risk assessment data
        
        Note over Server: Wait for webhook response
        
        alt Webhook: acquiring.payment_intent.succeeded
            Note over Server,Client: Frictionless - No OTP required
            UQPay->>Server: Webhook (succeeded)
            Server-->>Client: Payment Success
            Client-->>User: Show Success Page
            
        else Webhook: acquiring.payment_intent.requires_action
            Note over Server,Client: Challenge required after assessment
            UQPay->>Server: Webhook (requires_action with redirect_to_url)
            Server-->>Client: Extract and send redirect URL
            Client->>ACS: Redirect to ACS Page
            User->>ACS: Enter OTP
            alt OTP Success
                ACS-->>Client: Redirect to return_url
                UQPay->>Server: Webhook (acquiring.payment_intent.succeeded)
            else OTP Failed
                ACS-->>Client: Redirect to Failure Page
                UQPay->>Server: Webhook (acquiring.payment_intent.failed)
            end
        end
    end

Step 1: Enable 3DS in Payment Request

To enable 3DS authentication, include the following parameters in your Payment Intent creation or confirmation request:

Step 2: Handle 3DS Authentication

After creating the Payment Intent with 3DS enabled, follow these steps based on the response:

Step 2.1: Check next_action in Response

The response will have status REQUIRES_CUSTOMER_ACTION. Examine the next_action field to determine next steps:

Case A: next_action.redirect_to_url exists

The response directly contains a redirect URL (no iframe). This indicates immediate challenge is required.

1. Extract next_action.redirect_to_url.url from the response
2. Redirect the customer to this URL for OTP verification
3. Wait for final webhook:
   • acquiring.payment_intent.succeeded - OTP verification succeeded
   • acquiring.payment_intent.failed - OTP verification failed or cancelled

Case B: next_action.redirect_iframe exists

The response contains an iframe for risk assessment. Proceed as follows:

1. Extract next_action.redirect_iframe.iframe from the response
2. Embed the iframe in your page and execute it (auto-submit)
3. Proceed to Step 2.2 to handle the webhook response

Step 2.2: Handle Webhook After iframe Execution (Case B only)

After the iframe executes, you will receive one of two webhooks:

Webhook Option 1: acquiring.payment_intent.succeeded

This means frictionless authentication succeeded. No further action required.

• Transaction completed without OTP
• Customer remains on your page
• Display success message

Webhook Option 2: acquiring.payment_intent.requires_action

This means challenge is required after risk assessment.

1. Extract next_action.redirect_to_url.url from the webhook payload
2. Redirect the customer to this URL for OTP verification
3. Wait for final webhook:
   • acquiring.payment_intent.succeeded - OTP verification succeeded
   • acquiring.payment_intent.failed - OTP verification failed or cancelled

Implementation Tip: Your integration must dynamically handle both response types (redirect_to_url vs redirect_iframe) and both webhook scenarios after iframe execution.

Note: For sandbox environment, use OTP 0101. For production, use the actual OTP sent to the cardholder.

Step 3: Handle Post-Authentication

After the payment process is completed:

1. Success: The customer will be redirected to the return_url specified in the initial request.
2. Failure: The customer will be redirected to the UQ payment failure page.

Sandbox Testing

For 3DS testing in the sandbox environment, use the following test cards to simulate different authentication modes:

Test Card - Frictionless 3DS

This card simulates a low-risk transaction that completes without customer interaction.

Test Card - Challenge 3DS

This card simulates a high-risk transaction that requires immediate OTP verification.

Test Card - Mixed 3DS

This card simulates a transaction that requires risk assessment first, then proceeds to challenge.