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.dynamic3DS
has 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.no3DS: Skip PayerMax 3DS authentication. However, it must be noted that whether 3DS authentication is ultimately triggered depends on the payment channel;
do3DS: Use PayerMax 3DS Service;
ext3DS: Use Independent 3DS service provider。
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 :
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"
}
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
Interface response example of Create Payment /orderAndPay API :
-- 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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
2.2 Dynamic 3DS Authentication - do3DS
Interface request example of Create Payment /orderAndPay API :
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"
}
}
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
Interface response example of Create Payment /orderAndPay API :
{
"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
4
5
6
7
8
9
10
11
2.3 Dynamic 3DS Authentication - ext3DS
Interface request example of Create Payment /orderAndPay API :
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"
}
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
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 wheneci
is 01, 02, 05, 06;xid
: Required wheneci
is 01, 02, 05, 06 andthreeDSVersion
starts with 1;dsTransactionId
: Required wheneci
is 01, 02, 05, 06 andthreeDSVersion
starts with 2.
Interface response example of Create Payment /orderAndPay API :
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
"outTradeNo": "uft_1748243102273J9TseUzteH",
"tradeToken": "T2025052607561687003664",
"status": "SUCCESS"
}
}
2
3
4
5
6
7
8
9