Skip to content
Global Payments Oceania API Global Payments Oceania API

PayUI 3DS Integration Guide

PayUI 3D Secure

PayUI supports 3D Secure 2 (3DS2), which helps authenticate cardholders and reduce fraud in online card payments.

What is 3D Secure

3DS2 is a global authentication protocol designed to prevent unauthorized use and reduce fraud losses for merchants. It adds an extra layer of protection to online payments by helping ensure that the person using a card online is the legitimate cardholder. 3DS2 addresses this fraud risk by authenticating the cardholder before the payment is authorized. It evaluates information such as the customer’s device type, location, and historical spending to help issuers identify legitimate customers and flag suspicious activity in real time. Based on the fraud risk, transactions can be challenged or declined as part of the checkout process by the cardholder’s bank.

How to Enable 3DS on PayUI

Enable 3DS for Account

Contact our support team to enable 3DS2 for your merchant account.

Enable 3DS When Creating Payment Request

Before initialising PayUI, when you create a payment request, you have to set the field transactionRequest.category.authenticationType to 3d_secure in the request. For complete field documentation, see Create a Payment Request.

Example Request:

{
    "reference": "INV-2026-001",
    "payment": {
        "amount": 3000,
        "currencyCode": "AUD",
        "description": "Payment for Order #12345"
    },
    "paymentMethods": [
        "card"
    ],
    "transactionRequest": {
        "category": {
            "frequency": "single",
            "captureType": "auto",
            "authenticationType": "3d_secure"
        }
    }
}

Note: Both merchant-level enablement and transactionRequest.category.authenticationType: 3d_secure are required. If either is missing, PayUI will not use 3DS for the payment.

Process 3DS Payment

When 3DS is enabled, and transactionRequest.category.authenticationType is set when creating payment request, PayUI will automatically load the required 3DS resources. Merchants should load only payui.js, no additional 3DS script is required.

Transaction Processing Flow

After customer clicks Pay Now button, necessary metadata will be sent to 3DS service provider for evaluating to determine its risk level:

  • Frictionless flow: Low-risk transactions are authenticated in the background, with no extra steps for the customer.
flowchart LR
A("Transaction Submitted")
B("Evaluate Risk")
C("Create Transaction")
D("Transaction Authroised")
A -- Metadata --> B
B -- Low Risk --> C
C --> D
  • Challenge flow: If a potentially high-risk transaction is detected, the issuer prompts the customer for verification via a one-time password or biometric confirmation.
flowchart LR
A("Transaction Submitted")
B("Evaluate Risk")
C("Customer Processes Authentication")
D("Transaction Declined")
E("Create Transaction")
F("Transaction Authroised")
G("Transaction Declined")
A -- Metadata --> B
B -- Challenge --> C
B -- High Rish --> D
C -- Authentication Passed --> E
C -- Authentication Failed--> G
E --> F

End-to-End Transaction Flow (Diagram)

This diagram shows the full 3DS2 PayUI flow from rendering the payment page through to server-side verification.

sequenceDiagram
    autonumber
    participant FrontEnd
    participant Merchant Server
    participant PayUI
    participant Single API
    participant 3DS Service Provider

    FrontEnd->>Merchant Server: Request payment page
    Merchant Server->>Single API: POST /paymentrequests <br/>(transactionRequest.category.authenticationType=3d_secure)
    Single API-->>Merchant Server: Payment Request ID
    Merchant Server->>Single API: POST /tokens (scope=payui and paymentrequestid)
    Single API-->>Merchant Server: One-Time Token (OTT)
    Merchant Server-->>FrontEnd: Render page with token
    FrontEnd->>PayUI: Load payui.js
    FrontEnd->>PayUI: GPAUNZ.PayUI.initialise(OTT)
    PayUI->>PayUI: Initialise 3DS
    PayUI-->>FrontEnd: Render iframe + emit 'initialise'
    FrontEnd->>FrontEnd: Customer enters card details
    PayUI-->>FrontEnd: Emit 'surchargeUpdate' (if enabled)
    FrontEnd->>PayUI: Customer clicks Pay Now
    PayUI->>3DS Service Provider: Send collected metadata from device
    3DS Service Provider-->>PayUI: Authentication result
    alt transaction is not challenged
        PayUI->>Single API: Create transaction <br/>(with authentication result)
    else transaction is challenged
        PayUI-->>FrontEnd: Render 3DS challenge popup
        FrontEnd->>FrontEnd: Customer completes the issuer’s authentication challenge
        FrontEnd->>PayUI: Complete challenged transaction
        PayUI->>3DS Service Provider: Verify transaction authentication result
        3DS Service Provider-->>PayUI: Authentication result
        PayUI->>Single API: Create transaction <br/>(with authentication result)
    end
    Single API-->>PayUI: Transaction Result and <br/> PaymentRequest state change
    PayUI-->>FrontEnd: Emit 'process' event