# 3DS认证 3D Secure（3DS）是一种安全协议，用于提高在线信用和债务卡交易的安全性。3DS让银行能够在即时验证卡片持有人身份。当卡主进行一个在线交易时，网站会要求他们输入一些特定信息，这些信息可以使银行确认卡主的身份。信息输入的方式包括手机验证码、银行预留身份信息（如预留手机号、证件号等）。若校验失败，则支付流程终止，交易无法完成。验证步骤通常在支付过程中自动进行，为用户提供了附加的安全保护，同时也保护了商家，防止欺诈交易。 这个系统最初由Visa公司开发，作为其"Verified by Visa"服务的一部分，后来也被Mastercard、American Express和其他很多银行采用。 PayerMax当前已全面支持了3D Secure 2，这个版本在用户体验、数据收集和处理以及移动交易安全等方面都进行了改进。交互示例如下： ![](https://img-cdn-sg.payermax.com/public/20250618-2df37331-f875-400e-9bcf-a5d53d91fabb.png) ## 1. 实现3DS认证 商户可以使用两种方式，实现3DS认证。 ### 1.1 使用PayerMax 3DS服务 默认情况下，商户在使用PayerMax的卡支付服务时，PayerMax本身会作为一个3DS的服务提供商，帮助商户同时处理3DS认证和支付。 ![](https://img-cdn-sg.payermax.com/public/20250618-3f7462ec-1fc8-4017-aab7-f775e5df1538.png) ### 1.2 使用第三方3DS服务商 市场上有一些机构具备独立3DS认证的能力（Hitrust/Cardinal/Cybs等）。商户可以选择使用自己信赖的3DS能力提供商，仅使用PayerMax的支付能力完成支付。 ![](https://img-cdn-sg.payermax.com/public/20250618-395006d3-5bed-4c02-a8e0-987d7ae111b1.png) ## 2. 使用动态3DS服务 除上述两种方式外，商户也可以申请开通动态3DS能力。开通动态3DS能力，须联系技术支持团队。 ::: danger 特别提醒： `使用动态3DS服务`只支持通过`纯API`集成模式接入。 ::: 开通后，商户在单次支付请求中，可以设置使用[独立3DS服务商](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/API/3ds.md#_1-2-使用第三方3ds服务商)或[PayerMax 3DS服务](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/API/3ds.md#_1-1-使用payermax-3ds服务)或不使用3DS。 仅[独立3DS服务商](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/API/3ds.md#_1-2-使用第三方3ds服务商)或[卡支付-纯API模式集成](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/API/card.md)，支持动态3DS。通过[/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay-delSuffixStart1/post.html) 创建支付时，商户可以通过`data.paymentDetail.cardInfo.dynamic3DS`设定是否使用3DS能力： - `data.paymentDetail.cardInfo.dynamic3DS`**为空**：不使用动态3DS，直接使用[PayerMax 3DS服务](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/API/3ds.md#_1-1-使用payermax-3ds服务)； - `data.paymentDetail.cardInfo.dynamic3DS`**有值**：使用动态3DS，根据商户的传入值决策是否发起3DS认证，以及使用何种3DS服务。 - no3DS：跳过PayerMax 3DS认证。但必须注意，最终是否触发3DS认证，取决于支付渠道； - do3DS：使用[PayerMax 3DS服务](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/API/3ds.md#_1-1-使用payermax-3ds服务)； - ext3DS：使用[独立3DS服务商](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/API/3ds.md#_1-2-使用第三方3ds服务商)。 ### 2.1 动态3DS认证-no3DS ::: danger 特别提醒： 即使设置为no3DS，支付渠道仍然可能发起3DS认证流程。 ::: [创建支付/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay-delSuffixStart1/post.html) 接口请求示例： ``` 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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay-delSuffixStart1/post.html) 接口响应示例： ``` 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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay-delSuffixStart1/post.html) 接口请求示例： ``` 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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay-delSuffixStart1/post.html) 接口响应示例： ``` 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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay-delSuffixStart1/post.html) 接口请求示例： ``` 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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay-delSuffixStart1/post.html) 接口响应示例： ``` json { "msg": "Success.", "code": "APPLY_SUCCESS", "data": { "outTradeNo": "uft_1748243102273J9TseUzteH", "tradeToken": "T2025052607561687003664", "status": "SUCCESS" } } ```