3DS认证
3D Secure（3DS）是一种安全协议，用于提高在线信用和债务卡交易的安全性。3DS让银行能够在即时验证卡片持有人身份。当卡主进行一个在线交易时，网站会要求他们输入一些特定信息，这些信息可以使银行确认卡主的身份。信息输入的方式包括手机验证码、银行预留身份信息（如预留手机号、证件号等）。若校验失败，则支付流程终止，交易无法完成。验证步骤通常在支付过程中自动进行，为用户提供了附加的安全保护，同时也保护了商家，防止欺诈交易。
这个系统最初由Visa公司开发，作为其"Verified by Visa"服务的一部分，后来也被Mastercard、American Express和其他很多银行采用。
PayerMax当前已全面支持了3D Secure 2，这个版本在用户体验、数据收集和处理以及移动交易安全等方面都进行了改进。交互示例如下：
1. 实现3DS认证
商户可以使用两种方式，实现3DS认证。
1.1 使用PayerMax 3DS服务
默认情况下，商户在使用PayerMax的卡支付服务时，PayerMax本身会作为一个3DS的服务提供商，帮助商户同时处理3DS认证和支付。
1.2 使用第三方3DS服务商
市场上有一些机构具备独立3DS认证的能力（Hitrust/Cardinal/Cybs等）。商户可以选择使用自己信赖的3DS能力提供商，仅使用PayerMax的支付能力完成支付。
2. 使用动态3DS服务
除上述两种方式外，商户也可以申请开通动态3DS能力。开通动态3DS能力，须联系技术支持团队。
特别提醒：
使用动态3DS服务只支持通过纯API集成模式接入。
开通后，商户在单次支付请求中，可以设置使用独立3DS服务商或PayerMax 3DS服务或不使用3DS。
仅独立3DS服务商或卡支付-纯API模式集成，支持动态3DS。通过/orderAndPay API 创建支付时，商户可以通过data.paymentDetail.cardInfo.dynamic3DS设定是否使用3DS能力：
data.paymentDetail.cardInfo.dynamic3DS为空：不使用动态3DS，直接使用PayerMax 3DS服务；data.paymentDetail.cardInfo.dynamic3DS有值：使用动态3DS，根据商户的传入值决策是否发起3DS认证，以及使用何种3DS服务。no3DS：跳过PayerMax 3DS认证。但必须注意，最终是否触发3DS认证，取决于支付渠道；
do3DS：使用PayerMax 3DS服务；
ext3DS：使用独立3DS服务商。
2.1 动态3DS认证-no3DS
特别提醒：
即使设置为no3DS，支付渠道仍然可能发起3DS认证流程。
创建支付/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" # 设定动态3DS，不使用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"
}
}'创建支付/orderAndPay API 接口响应示例：
json
-- 支付渠道发起3DS认证
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
# 支付渠道3DS认证地址
"redirectUrl": "https://gpay.com.tr/Whitelabel/order/3DS_08UKL9BAcR",
"outTradeNo": "2024051218007331272785789980672",
"tradeToken": "T2024052223464910035619",
"status": "PENDING"
}
}
-- 支付渠道未发起3DS认证
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
"outTradeNo": "2024051218007331272785789980672",
"tradeToken": "T2024052223464910035619",
"status": "SUCCESS"
}
}2.2 动态3DS认证-do3DS
创建支付/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查询和回调返回",
"frontCallbackUrl": "https://[your domain name]/[your callback URL]",
"notifyUrl": "https://[your domain name]/[your notify URL]",
"integrate": "Direct_Payment",
"paymentDetail": {
"paymentMethodType": "CARD",
"targetOrg": "VISA",
"tokenForFutureUse": "true",
"cardInfo": {
"cardIdentifierNo": "53783211112320",
"cardHolderFullName": "张秀",
"cardExpirationMonth": "04",
"cardExpirationYear": "30",
"cvv": "232",
"dynamic3DS": "do3DS" # 设定动态3DS，使用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"
}
}
}'创建支付/orderAndPay API 接口响应示例：
json
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
# 3DS认证地址 或 DDC采集地址
"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 动态3DS认证-ext3DS
创建支付/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" # 设定动态3DS，使用外部3DS服务
},
"info3DSecure": { # 使用外部3DS服务时，必传该对象
"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表示商户使用的第三方3DS服务商的验证信息，对象属性的值符合如下规则：
eci：必填，取值是两位数字，包括00、01、02、03、05、06、07；threeDSVersion：必填，只能以1或者2开头。当以1开头，表示3DS 1.0；当以2开头，表示3DS 2.0；cavv：当eci是01、02、05、06时，必填；xid: 当eci是01、02、05、06 且threeDSVersion以1开头，则必填；dsTransactionId: 当eci是01、02、05、06且threeDSVersion以2开头，则必填。
创建支付/orderAndPay API 接口响应示例：
json
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
"outTradeNo": "uft_1748243102273J9TseUzteH",
"tradeToken": "T2025052607561687003664",
"status": "SUCCESS"
}
}