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:

​

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.