PayerMax

English

简体中文

English

简体中文

3D Secure ​

3D Secure (3DS) is a security protocol used to improve the security of online credit and debt card transactions. 3DS allows banks to instantly verify the identity of cardholders. When a cardholder makes an online transaction, the website will ask them to enter certain information that allows the bank to confirm the cardholder's identity. Information can be entered in the form of a mobile phone verification code or bank-reserved identity information (such as a reserved mobile phone number, ID number, etc.). If the verification fails, the payment process is terminated and the transaction cannot be completed. The verification step is usually performed automatically during the payment process, providing additional security for users and protecting merchants from fraudulent transactions.

The system was originally developed by Visa as part of its "Verified by Visa" service, and has since been adopted by Mastercard, American Express, and many other banks.

PayerMax currently fully supports 3D Secure 2, which has improved user experience, data collection and processing, and mobile transaction security. The following is an example of the interaction:

1. Implementing 3D Secure Authentication ​

Merchants can use two methods to implement 3DS authentication.

1.1 Using PayerMax 3DS Service ​

By default, when merchants use PayerMax's card payment service, PayerMax itself will act as a 3DS service provider to help merchants handle both 3DS authentication and payment.

1.2 Using a third-party 3DS service provider ​

There are some institutions in the market that have independent 3DS certification capabilities (Hitrust/Cardinal/Cybs, etc.). Merchants can choose to use their own trusted 3DS capability providers and only use PayerMax's payment capabilities to complete payments.

2. Using Dynamic 3DS Services ​

In addition to the above two methods, merchants can also apply to activate the dynamic 3DS capability. To activate the dynamic 3DS capability, you must contact the technical support team.

Special reminder:

Using dynamic 3DS services is only supported through Direct API integration mode.

After activation, merchants can set up to use independent 3DS service providers or PayerMax 3DS service or not use 3DS in a single payment request.

Dynamic 3DS is only supported in [Card Payment - Pure API Integration Mode]. Using Create Payment /orderAndPay API to create payment, Merchants can set whether to use 3DS capabilities through data.paymentDetail.cardInfo.dynamic3DS:

  • data.paymentDetail.cardInfo.dynamic3DS is empty: Do not use Dynamic 3DS, but directly use PayerMax 3DS service;

  • data.paymentDetail.cardInfo.dynamic3DShas value: Use dynamic 3DS and decide whether to initiate 3DS authentication and which 3DS service to use based on the value passed in by the merchant.

2.1 Dynamic 3DS Authentication - no3DS ​

Special reminder:

Even if set to no3DS, the payment channel may still initiate the 3DS authentication process.

Interface request example of Create Payment /orderAndPay API :

js
curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'sign: FPFMM3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A==' \
  --data '{
    "version": "1.4",
    "keyVersion": "1",
    "requestTime": "2025-05-22T11:00:40.614+00:00",
    "appId": "test86c2ee404ce1bb958e5a8c623667",
    "merchantNo": "TEST20118126922",
    "data": {
        "outTradeNo": "2024051218007331272785789980672",
        "integrate": "Direct_Payment",
        "subject": "Online Store",
        "totalAmount": 50.59,
        "currency": "USD",
        "country": "US",
        "userId": "123324",
        "paymentDetail": {
            "paymentMethodType": "CARD",
            "cardInfo": {
                "cardIdentifierNo": "47581523430442",
                "cardHolderFullName": "Heather Christensen",
                "cardExpirationMonth": "10",
                "cardExpirationYear": "27",
                "cvv": "230",
                "dynamic3DS": "no3DS" # Set up Dynamic 3DS, do not use 3DS
            },
            "buyerInfo": {
                "firstName": "Miler",
                "lastName": "patrick",
                "phoneNo": "+18016733977",
                "email": "buyer@gmail.com",
                "clientIp": "2601:680:ce80:9be9:61a5:c9e3:64cc:24cc",
                "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_3_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/22D82 [FBAN/FBIOS;FBAV/509.0.0.22.14;FBBV/721998097;FBDV/iPhone14,5;FBMD/iPhone;FBSN/iOS;FBSV/18.3.2;FBSS/3;FBID/phone;FBLC/en_US;FBOP/5;FBRV/724397281;IABMV/1]"
            }
        },
        "goodsDetails": [
            {
                "goodsId": "16068102554744342936791560\t",
                "goodsName": "Lions Mane - Lions Mane Mushroom Supplement- Lions Mane Tincture - Natural Immune Support - Lions Mane Tincture for Memory, Focus & Clarity - Daily Mushroom Supplement - Vegan",
                "quantity": "1",
                "price": "49.97",
                "showUrl": "https://your.top/products/nocera®lions-mane---lions-mane-mushroom-supplement--lions-mane-tincture---natural-immune-support---lions-mane-tincture-for-memory-focus-clarity---daily-mushroom-supplement---vegan\t",
                "goodsCategory": "Preferential"
            }
        ],
        "shippingInfo": {
            "firstName": "Heather",
            "lastName": "Christensen",
            "phoneNo": "+1336734977",
            "email": "your@gmail.com",
            "address1": "724 W 1236 N",
            "city": "Farmington",
            "state": "UT",
            "country": "US",
            "zipCode": "84025"
        },
        "billingInfo": {
            "email": "your@gmail.com",
            "address1": "724 W 1236 N",
            "city": "Farmington",
            "country": "US",
            "state": "UT",
            "zipCode": "84025"
        },
        "terminalType": "WEB",
        "frontCallbackUrl": "https://hooks.your.com/static/3d_secure_2/return?id=pi_7iqsSiLzx7YUUxiHKCVH9XdU"
    }
}'

Interface response example of Create Payment /orderAndPay API :

json
-- Payment channel initiates 3DS authentication
{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        # Payment channel 3DS authentication address
        "redirectUrl": "https://gpay.com.tr/Whitelabel/order/3DS_08UKL9BAcR",
        "outTradeNo": "2024051218007331272785789980672",
        "tradeToken": "T2024052223464910035619",
        "status": "PENDING"
    }
}

-- The payment channel did not initiate 3DS authentication
{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "outTradeNo": "2024051218007331272785789980672",
        "tradeToken": "T2024052223464910035619",
        "status": "SUCCESS"
    }
}

2.2 Dynamic 3DS Authentication - do3DS ​

Interface request example of Create Payment /orderAndPay API :

js
curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'sign: FPFMM3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A==' \
  --data '{
    "version": "1.4",
    "keyVersion": "1",
    "requestTime": "2025-05-22T14:08:54.887+00:00",
    "appId": "test0279df374af8871d1da97c673894",
    "merchantNo": "TEST13827355079",
    "data": {
        "terminalType": "WEB",
        "outTradeNo": "R--Test1747922934887",
        "requestId": "",
        "subject": "SUCCESS",
        "totalAmount": "0.1",
        "currency": "SAR",
        "country": "SA",
        "userId": "apptest0416",
        "language": "",
        "expireTime": "1800",
        "reference": "Reference query and callback return",
        "frontCallbackUrl": "http://www.frontCallbackUrl.com",
        "notifyUrl": "http://www.notifyUrl.com",
        "integrate": "Direct_Payment",
        "paymentDetail": {
            "paymentMethodType": "CARD",
            "targetOrg": "VISA",
            "tokenForFutureUse": "true",
            "cardInfo": {
                "cardIdentifierNo": "53783211112320",
                "cardHolderFullName": "张秀",
                "cardExpirationMonth": "04",
                "cardExpirationYear": "30",
                "cvv": "232",
                "dynamic3DS": "do3DS" # Set up Dynamic 3DS and use PayerMax 3DS
            },
            "buyerInfo": {
                "firstName": "zhang",
                "middleName": "middleName",
                "lastName": "Simth",
                "phoneNo": "9032030628",
                "email": "your@google.com",
                "clientIp": "124.156.108.193",
                "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36",
                "taxType": "CNPJ",
                "taxNo": "359.%#@"
            }
        },
        "envInfo": {
            "deviceId": "",
            "deviceLanguage": "zh_CN",
            "screenHeight": "768",
            "screenWidth": "1024"
        },
        "goodsDetails": [
            {
                "goodsId": "D002",
                "goodsName": "韩版修身牛仔裤男",
                "quantity": "2",
                "price": "500",
                "goodsCurrency": "IDR",
                "showUrl": "http://xxxx.your.png",
                "goodsCategory": "电脑"
            }
        ],
        "shippingInfo": {
            "firstName": "firstName",
            "middleName": "middleName",
            "lastName": "lastName",
            "phoneNo": "65423234567",
            "email": "your@fasd.com",
            "address1": "1-1900 MARKET STREET, Philadelphia, PA 19103",
            "address2": "233",
            "city": "Philadelphia",
            "region": "AF",
            "state": "PA",
            "country": "SA",
            "zipCode": "432123"
        },
        "billingInfo": {
            "firstName": "zhang",
            "middleName": "qiong",
            "lastName": "xiu",
            "email": "",
            "phoneNo": "12323436789",
            "address1": "281 Liberty Street, 39th Floor, New York, NY 10005",
            "address2": "",
            "city": "New York,1",
            "region": "NY1",
            "state": "",
            "country": "US",
            "zipCode": "10005"
        },
        "riskParams": {
            "registerName": "lily",
            "regTime": "2023-07-01 12:08:34",
            "liveCountry": "VN",
            "payerAccount": "987654XXX",
            "payerName": "lily",
            "taxId": "1234567890"
        }
    }
}'

Interface response example of Create Payment /orderAndPay API :

json
{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        # 3DS authentication address or DDC collection address
        "redirectUrl": "https://cashier-n-pre.payermax.com/static/processApiV2.html?tradeToken=T2023052214224172000075&integrate=DIRECT_API&country=SA&payRequestNo=20250522140855PP7306124122000330T11&merchantId=TEST13827355079&merchantAppId=test0279df374af8871d1da97c673894&token=97041758c3a8484487dd1f112c962432&orderLan=en&countryLan=ar&strategyLan=OULBC&pmaxLinkV=1",
        "outTradeNo": "R--Test1747922934887",
        "tradeToken": "T2023052214224172000075",
        "status": "PENDING"
    }
}

2.3 Dynamic 3DS Authentication - ext3DS ​

Interface request example of Create Payment /orderAndPay API :

js
curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'sign: FPFMM3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A==' \
  --data '{
    "version": "1.4",
    "keyVersion": "1",
    "requestTime": "2025-05-22T11:00:40.614+00:00",
    "appId": "test86c2ee404ce1bb958e5a8c623667",
    "merchantNo": "TEST20118126922",
    "data": {
        "outTradeNo": "2024051218007331272785789980672",
        "integrate": "Direct_Payment",
        "subject": "Online Store",
        "totalAmount": 50.59,
        "currency": "USD",
        "country": "US",
        "userId": "123324",
        "paymentDetail": {
            "paymentMethodType": "CARD",
            "cardInfo": {
                "cardIdentifierNo": "47581523430442",
                "cardHolderFullName": "Heather Christensen",
                "cardExpirationMonth": "10",
                "cardExpirationYear": "27",
                "cvv": "230",
                "dynamic3DS": "ext3DS" # Set up Dynamic 3DS and use external 3DS services
            },
            "info3DSecure": { # This object must be passed when using external 3DS services.
                "eci": "05", 
                "threeDSVersion": "2.2.0", 
                "cavv": "MAAAAAAAAAAAAAAAAAAAAAAAAAA", 
                "xid": "123", 
                "dsTransactionId": "683001f5-3805-423a-b580-638e4b2093b3" 
            },
            "buyerInfo": {
                "firstName": "Miler",
                "lastName": "patrick",
                "phoneNo": "+18016733977",
                "email": "buyer@gmail.com",
                "clientIp": "2601:680:ce80:9be9:61a5:c9e3:64cc:24cc",
                "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_3_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/22D82 [FBAN/FBIOS;FBAV/509.0.0.22.14;FBBV/721998097;FBDV/iPhone14,5;FBMD/iPhone;FBSN/iOS;FBSV/18.3.2;FBSS/3;FBID/phone;FBLC/en_US;FBOP/5;FBRV/724397281;IABMV/1]"
            }
        },
        "goodsDetails": [
            {
                "goodsId": "16068102554744342936791560\t",
                "goodsName": "Lions Mane - Lions Mane Mushroom Supplement- Lions Mane Tincture - Natural Immune Support - Lions Mane Tincture for Memory, Focus & Clarity - Daily Mushroom Supplement - Vegan",
                "quantity": "1",
                "price": "49.97",
                "showUrl": "https://your.top/products/nocera®lions-mane---lions-mane-mushroom-supplement--lions-mane-tincture---natural-immune-support---lions-mane-tincture-for-memory-focus-clarity---daily-mushroom-supplement---vegan\t",
                "goodsCategory": "Preferential"
            }
        ],
        "shippingInfo": {
            "firstName": "Heather",
            "lastName": "Christensen",
            "phoneNo": "+1336734977",
            "email": "your@gmail.com",
            "address1": "724 W 1236 N",
            "city": "Farmington",
            "state": "UT",
            "country": "US",
            "zipCode": "84025"
        },
        "billingInfo": {
            "email": "your@gmail.com",
            "address1": "724 W 1236 N",
            "city": "Farmington",
            "country": "US",
            "state": "UT",
            "zipCode": "84025"
        },
        "terminalType": "WEB",
        "frontCallbackUrl": "https://hooks.your.com/static/3d_secure_2/return?id=pi_7iqsSiLzx7YUUxiHKCVH9XdU"
    }
}'

paymentDetail.info3DSecure represents the verification information of the third-party 3DS service provider used by the merchant. The value of the object attribute conforms to the following rules:

  • eci: Required, the value is two digits, including 00, 01, 02, 03, 05, 06, 07;

  • threeDSVersion: Required, can only start with 1 or 2. When it starts with 1, it means 3DS 1.0; when it starts with 2, it means 3DS 2.0;

  • cavv: Required when eci is 01, 02, 05, 06;

  • xid: Required when eci is 01, 02, 05, 06 and threeDSVersion starts with 1;

  • dsTransactionId: Required when eci is 01, 02, 05, 06 and threeDSVersion starts with 2.

Interface response example of Create Payment /orderAndPay API :

json
{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "outTradeNo": "uft_1748243102273J9TseUzteH",
        "tradeToken": "T2025052607561687003664",
        "status": "SUCCESS"
    }
}

Was this page helpful?

Thank you for your help in improving PayerMax Product Docs！

Last updated:

Released under the MIT License.

Copyright © 2023-present PayerMax