3D Secure (3DS) Configuration

Overview

3D Secure (3DS) is an authentication protocol that adds an extra layer of security for online card payments. When enabled, cardholders are redirected to their card issuer's authentication page to verify their identity before the payment is processed.

By default, 3DS is enabled on the Lesspay2 platform. The three_ds parameter allows merchants to explicitly control 3DS behavior on a per-transaction basis.

Note: Even when 3DS is explicitly disabled (enabled: false), the payment channel (e.g., Checkout.com) may still enforce 3DS based on its own risk rules or regulatory requirements.

Standard (Non-3DS)

Card number, CVV, expiry date

Faster checkout but higher risk

Recommended for low-value transactions

3D Secure (3DS)

Additional authentication layer (OTP, biometric, PIN)

Frictionless flow: Risk-based authentication, no user action required

Challenge flow: User prompted for additional verification

Required for Strong Customer Authentication (SCA) in many regions

Reduces fraud and shifts liability to issuer

Applicable Scenarios

Integration Mode	Supported
Cashier Mode (`pay_access_type=1`) — Payment Session	Yes
OpenAPI Mode (`pay_access_type=2`) — Direct Card Payment	Yes
OpenAPI Mode — Token Payment	No

Parameter Specification

The three_ds parameter is placed inside the channel_extra object of the Create Order request.

Structure

Parameter	Type	Required	Description
`channel_extra.three_ds`	Object	No	3D Secure configuration object
`channel_extra.three_ds.enabled`	Boolean	No	Whether to enable 3DS authentication

`three_ds.enabled` Behavior

Value	Behavior
Not provided / `null`	Uses platform default (3DS enabled)
`true`	Explicitly enable 3DS authentication
`false`	Explicitly disable 3DS (subject to channel override)

Integration Guide

1. OpenAPI Mode — Direct Card Payment

In OpenAPI Mode with direct card payment (pay_access_type=2, extra_type=card), add the three_ds object alongside the existing card_data in channel_extra.

Endpoint

POST /api/global/v1/pay/create-order

Request Example (3DS Enabled)

{
    "target_amount": "100.00",
    "target_currency": "USD",
    "transaction_type": "PAY_IN",
    "notify_url": "https://merchant.example.com/notify",
    "request_id": "M20260228150001",
    "fail_url": "https://merchant.example.com/fail",
    "success_url": "https://merchant.example.com/success",
    "product_name": "Test Product",
    "description": "Test Order",
    "way_type": "CARD_PAYMENT",
    "api_version": "V2",
    "pay_access_type": 2,
    "channel_extra": {
        "extra_type": "card",
        "card_data": {
            "number": "4242424242424242",
            "expiry_month": 12,
            "expiry_year": 2027,
            "cvv": "100",
            "store_for_future_use": false
        },
        "three_ds": {
            "enabled": true
        }
    }
}

Request Example (3DS Disabled)

{
    "target_amount": "100.00",
    "target_currency": "USD",
    "transaction_type": "PAY_IN",
    "notify_url": "https://merchant.example.com/notify",
    "request_id": "M20260228150002",
    "fail_url": "https://merchant.example.com/fail",
    "success_url": "https://merchant.example.com/success",
    "product_name": "Test Product",
    "description": "Test Order",
    "way_type": "CARD_PAYMENT",
    "api_version": "V2",
    "pay_access_type": 2,
    "channel_extra": {
        "extra_type": "card",
        "card_data": {
            "number": "4242424242424242",
            "expiry_month": 12,
            "expiry_year": 2027,
            "cvv": "100"
        },
        "three_ds": {
            "enabled": false
        }
    }
}

Response Handling

The response behavior depends on whether 3DS is triggered. For Direct Card Payment and Token Payment modes, the order_data includes a 3ds object with the authentication result.

When 3DS is required — Response contains payDataType: "payurl" and 3ds result:

{
    "code": 0,
    "msg": "SUCCESS",
    "data": {
        "order_data": {
            "mchOrderNo": "M20260228150001",
            "orderState": 1,
            "payData": "https://authentication-devices.sandbox.checkout.com/sessions-interceptor/sid_xxxxx",
            "payDataType": "payurl",
            "payOrderDetailId": "PD2011337514476363778",
            "payOrderDetailIdEncode": "3ff04ea391ed7163c6943e39e774dbf...",
            "payOrderDetailState": 1,
            "payOrderId": "P2011337513994018818",
            "3ds": {
                "downgraded": false,
                "enrolled": "Y",
                "upgrade_reason": "sca_retry"
            }
        },
        "pay_order_id": "P2011337513994018818"
    }
}

→ Redirect the user to the payData URL to complete 3DS verification.

When 3DS is not required — Response has no payDataType / payData, 3ds :

{
    "code": 0,
    "msg": "SUCCESS",
    "data": {
        "order_data": {
            "mchOrderNo": "M20260228150002",
            "orderState": 1,
            "payOrderDetailId": "PD2011293075558170625",
            "payOrderDetailIdEncode": "3ff04ea391ed7163c6943e39e774dbf...",
            "payOrderDetailState": 1,
            "payOrderId": "P2011293075021299713"
        },
        "pay_order_id": "P2011293075021299713"
    }
}

→ Payment is processing directly. Wait for the webhook callback for final status.

2. Cashier Mode — Payment Session

In Cashier Mode (pay_access_type=1), the three_ds parameter can be passed in two places:

In the Create Order request (via channel_extra.three_ds) — same as OpenAPI Mode

In the Payment Session request — when the frontend cashier page calls the session creation API

Create Order Request Example

{
    "target_amount": "100.00",
    "target_currency": "USD",
    "transaction_type": "PAY_IN",
    "notify_url": "https://merchant.example.com/notify",
    "request_id": "M20260228160001",
    "fail_url": "https://merchant.example.com/fail",
    "success_url": "https://merchant.example.com/success",
    "product_name": "Test Product",
    "description": "Test Order",
    "way_type": "CARD_PAYMENT",
    "api_version": "V2",
    "pay_access_type": 1,
    "channel_extra": {
        "three_ds": {
            "enabled": true
        }
    }
}

Payment Session API

The cashier page calls the following endpoint to create a Checkout Payment Session, which also accepts the three_ds parameter:

POST /api/cashier/checkout-payment

Request Body:

Parameter	Type	Required	Description
`mchNoEncode`	String	Yes	Encrypted merchant number
`payOrderIdEncode`	String	Yes	Encrypted payment order ID
`three_ds`	Object	No	3DS configuration
`three_ds.enabled`	Boolean	No	Whether to enable 3DS

Request Example:

{
    "mchNoEncode": "encrypted_merchant_number",
    "payOrderIdEncode": "encrypted_order_id",
    "three_ds": {
        "enabled": true
    }
}

3DS Flow Diagram

With 3DS Enabled

Merchant                  Lesspay2                Checkout.com            Card Issuer
   |                         |                         |                      |
   |--- Create Order ------->|                         |                      |
   |   (three_ds.enabled=true)                         |                      |
   |                         |--- Payment Request ---->|                      |
   |                         |   (3DS enabled)         |                      |
   |                         |<-- Redirect URL --------|                      |
   |<-- payDataType=payurl --|                         |                      |
   |                         |                         |                      |
   |--- Redirect User ------>|----------- 3DS Page --->|------- Auth -------->|
   |                         |                         |<------ Result -------|
   |                         |<-- Payment Result ------|                      |
   |<-- Webhook Callback ----|                         |                      |

With 3DS Disabled

Merchant                  Lesspay2                Checkout.com
   |                         |                         |
   |--- Create Order ------->|                         |
   |  (three_ds.enabled=false)                         |
   |                         |--- Payment Request ---->|
   |                         |   (3DS disabled)        |
   |                         |<-- Payment Result ------|
   |<-- Webhook Callback ----|                         |

Important: Even with three_ds.enabled=false, Checkout.com may still enforce 3DS based on card issuer policies, regional regulations (e.g., SCA in Europe), or risk assessment. In such cases, the response will still contain a redirect URL for 3DS authentication.

3DS Response Data

The platform returns 3DS authentication result in multiple places. The availability depends on the integration mode:

Data Location	Direct Card Payment	Token Payment	Payment Session (Cashier)
Create Order response `order_data.3ds`	Yes	Yes	No (payment not yet completed)
Webhook callback `channel_biz_data.3ds`	Yes	Yes	Yes
Query Order API `channel_biz_data.3ds`	Yes	Yes	Yes

`3ds` Object Structure

Parameter	Type	Description
`3ds`	Object	3DS authentication result
`3ds.downgraded`	Boolean	Whether the 3DS authentication was downgraded to a non-3DS payment
`3ds.enrolled`	String	Card enrollment status. `"Y"` = enrolled, `"N"` = not enrolled, `"U"` = unknown
`3ds.upgrade_reason`	String	Reason for 3DS upgrade (e.g., `"sca_retry"`) if the transaction was upgraded to 3DS

Field Value Reference

3ds.downgraded

Value	Description
`false`	3DS authentication was performed normally
`true`	3DS was downgraded — the payment was processed without full 3DS authentication (e.g., issuer does not support 3DS)

3ds.enrolled

Value	Description
`"Y"`	Card is enrolled in 3DS — cardholder authentication was performed
`"N"`	Card is not enrolled in 3DS
`"U"`	Enrollment status unknown

3ds.upgrade_reason

Value	Description
`"sca_retry"`	Transaction was retried with 3DS due to Strong Customer Authentication (SCA) requirements
`null` / not present	No upgrade was applied

1. Create Order Response (Direct Card / Token Payment)

For Direct Card Payment (extra_type=card) and Token Payment (extra_type=token), the 3ds object is returned in order_data immediately:

{
    "code": 0,
    "msg": "SUCCESS",
    "data": {
        "order_data": {
            "mchOrderNo": "M20260228150001",
            "orderState": 1,
            "payData": "https://authentication-devices.sandbox.checkout.com/...",
            "payDataType": "payurl",
            "payOrderDetailId": "PD2011337514476363778",
            "payOrderId": "P2011337513994018818",
            "3ds": {
                "downgraded": false,
                "enrolled": "Y",
                "upgrade_reason": "sca_retry"
            }
        },
        "pay_order_id": "P2011337513994018818"
    }
}

Note: For Payment Session (Cashier Mode), the 3ds object is not included in the Create Order response because the payment has not yet been processed at that point. The 3DS result will be available through the Webhook callback after the user completes payment.

2. Webhook Callback (All Modes)

After payment is completed (success or failure), the 3ds result is included in the channel_biz_data of the Webhook callback notification. This applies to all three modes (Direct Card, Token, and Payment Session):

{
    "api_version": "V2",
    "description": "Lesspay Order",
    "fail_url": "https://www.example.com/fail",
    "order_status": "SUCCEED",
    "order_status_int": 2,
    "pay_order_id": "P2011789219984105474",
    "product_name": "Lesspay Order",
    "request_id": "M20260228150001",
    "success_url": "https://www.example.com/success",
    "target_amount": "100.00",
    "target_currency": "USD",
    "channel_biz_data": {
        "card_token": "src_3oqxta2juhbevjaw72pgorkd5e",
        "issuer": "CKO, WHERE THE WORLD CHECKS OUT",
        "issuer_country": "GB",
        "3ds": {
            "downgraded": false,
            "enrolled": "Y",
            "upgrade_reason": "sca_retry"
        }
    }
}

3. Query Order API (All Modes)

The 3ds result is also available when querying order details via the Query Order API:

{
    "code": 0,
    "msg": "SUCCESS",
    "data": {
        "pay_order_id": "P2011789219984105474",
        "request_id": "M20260228150001",
        "order_status": "SUCCEED",
        "order_status_int": 2,
        "target_amount": "100.00",
        "target_currency": "USD",
        "channel_biz_data": {
            "card_token": "src_3oqxta2juhbevjaw72pgorkd5e",
            "issuer": "CKO, WHERE THE WORLD CHECKS OUT",
            "issuer_country": "GB",
            "3ds": {
                "downgraded": false,
                "enrolled": "Y",
                "upgrade_reason": "sca_retry"
            }
        }
    }
}

Note: The 3ds object is only present when the payment was processed through the Checkout.com channel. If 3DS was not triggered at all, this object may be absent.

Backward Compatibility

No breaking changes: If three_ds is not provided in the request, the platform behavior remains exactly the same as before (3DS enabled by default).

Existing integrations do not need any modification.

Token payments are unaffected — the three_ds parameter is ignored for token-based transactions.

3D Secure (3DS) Configuration

Overview#

Standard (Non-3DS)#

3D Secure (3DS)#

Applicable Scenarios#

Parameter Specification#

Structure#

three_ds.enabled Behavior#

Integration Guide#

1. OpenAPI Mode — Direct Card Payment#

Endpoint#

Request Example (3DS Enabled)#

Request Example (3DS Disabled)#

Response Handling#

2. Cashier Mode — Payment Session#

Create Order Request Example#

Payment Session API#

3DS Flow Diagram#

With 3DS Enabled#

With 3DS Disabled#

3DS Response Data#

3ds Object Structure#

Field Value Reference#

1. Create Order Response (Direct Card / Token Payment)#

2. Webhook Callback (All Modes)#

3. Query Order API (All Modes)#

Backward Compatibility#