更多功能
发起授权支付时，您可以根据自身业务需求选择是否使用更多功能。本文为您提供更多功能的详细说明及使用方式。
设置 3D 认证
通过设定 is3DSAuthentication 参数的值，指定某笔交易是否进行 3D 认证：
- is3DSAuthentication 值为
true：该笔交易触发 3D 验证。 - is3DSAuthentication 值为
false，收单机构会决策是否触发 3D 验证。如果您接入了蚂蚁独立风控能力，会由蚂蚁独立风控优先决策是否触发 3D 验证。 - is3DSAuthentication 不设置值或不传：则等同于该参数值为
false的情况，收单机构会决策是否触发 3D 验证。如果您接入了蚂蚁独立风控能力，会由蚂蚁独立风控优先决策是否触发 3D 验证。
API 集成方式下，在 支付 接口中设置该字段； SDK 集成方式下，在 支付会话创建 接口中设置该字段。
AVS 验证
地址验证系统（AVS）用于验证账单地址是否与信用卡持卡人的地址匹配，可有效防止欺诈交易的发生。若您的机构支持 AVS 校验服务，当买家输入持卡人的账单地址和邮编后，AVS 系统会将该信息与发卡机构中存储的对应信息进行比对，如果该信息与发卡机构记录中的信息不匹配，则交易可能会被拒绝或需要进行额外的身份验证。支付 AVS 验证可帮助减少信用卡欺诈风险。
在不同的集成方式下，APO 支持您采取如下的方式发起 AVS 校验，APO 会将 AVS 信息传给您的收单机构：
- 在 API 集成方式下：
- 您需要在调用 支付 接口时传入 billingAddress 参数。
- 在 SDK 集成方式下，您可以通过如下两种方式接入该能力：
- 您可以联系技术支持，在 SDK 为买家提供的支付信息收集页下配置买家账单地址收集框。
- 您也可以选择自己传入提前收集好的账单信息，在 支付会话创建 接口中传入 billingAddress 参数以发起 AVS 校验。同时，在 Web/WAP 端也支持您通过 SDK 的
submit方法传入billingAddress 参数。
您可通过 支付结果通知 或 支付结果查询 响应的 avsResultRaw 字段获得 AVS 校验的结果。
存储卡信息
您可以为买家提供绑卡服务，即支持买家在首次支付时选择存储卡信息，以便下次支付时无需再次输入卡信息。下图展示了用户选择绑卡后，再次支付时的下单页面：
图 1. 用户绑卡后续支付页面
API 集成方式
API 集成模式下，收集完买家卡信息后，您可以选择让 APO 帮助您存储卡信息，也可以选择自行存储卡信息。
APO 存储卡信息（推荐）
自行存储卡信息
当买家在您的页面上选择存储卡片信息，您需要将收集好的卡信息通过 支付 接口传给 APO 并指定 tokenize 字段为 true。APO 会将卡信息生成对应的卡令牌 (cardToken)，授权支付成功后，您可以通过接收异步通知或通过 支付结果查询 接口主动查询的方式获取卡令牌 (cardToken) 及脱敏后的卡号 (cardNo)。您需将获取到的卡令牌与脱敏卡号等信息与买家信息进行关联并存储，以用于后续支付。
以下示例展示了 APO 存储卡信息模式下，您需要发送给 APO 的 支付 请求：
copy
{
"settlementStrategy": {
"settlementCurrency": "EUR"
},
"productCode": "CASHIER_PAYMENT",
"paymentNotifyUrl": "http://gol.alipay.net:8080/amsdemo/record/notify?env=main_GROUP&paymentMethodType=CARD",
"paymentRequestId": "2****************2",
"paymentRedirectUrl": "http://gol.alipay.net:8080/amsdemo/result?paymentRequestId=2023070458941025622196",
"paymentFactor": {
"isAuthorization": true
},
"paymentMethod": {
"paymentMethodMetaData": {
"recurringType": "",
"cvv": "123",
"is3DSAuthentication": false,
"isCardOnFile": false,
"expiryMonth": "05",
"tokenize": true,
"expiryYear": "26",
"billingAddress": {
"zipCode": "310000",
"address2": "gongzhuan Road",
"city": "hangzhou",
"state": "zhejiang",
"region": "CN"
},
"cardNo": "****1846"
},
"paymentMethodType": "CARD"
},
"paymentExpiryTime": "2025-11-27T12:00:01+08:30",
"paymentAmount": {
"currency": "EUR",
"value": "8204"
},
"merchantRegion": "",
"order": {
"orderAmount": {
"currency": "EUR",
"value": "8204"
},
"referenceOrderId": "2********************0",
"shipping": {
"shippingName": {
"firstName": "Li",
"lastName": "Kyle",
"fullName": "Kyle Li"
},
"shippingCarrier": "DHL",
"shippingPhoneNo": "**********19",
"shipToEmail": "exam***@163.com",
"shippingAddress": {
"zipCode": "310000",
"address2": "gongzhuan Road",
"city": "hangzhou",
"state": "zhejiang",
"region": "CN"
}
},
"goods": [
{
"referenceGoodsId": "2******************7",
"goodsUrl": "qinghailipipeng",
"goodsCategory": "chemical",
"goodsUnitAmount": {
"currency": "EUR",
"value": "8204"
},
"goodsQuantity": "1",
"goodsName": "boom",
"goodsSkuName": "boom boom room",
"goodsBrand": "antom boom"
}
],
"env": {
"clientIp": "1.1.1.1",
"osType": "IOS",
"terminalType": "WAP"
},
"orderDescription": "ANTOM_ZZ",
"buyer": {
"referenceBuyerId": "2******************7",
"buyerName": {
"firstName": "Li",
"lastName": "Kyle",
"fullName": "Kyle Li"
}
}
}
}当绑卡买家再次进行支付时，您需要完成以下操作：
- 在收银台页面为买家展示脱敏后的卡信息。
- 调用 支付 接口，并传入以下参数：
- paymentMethodId: 值为 cardToken 的参数值（cardToken 可从原始绑卡交易对应的 支付通知 和 支付结果查询 接口返回的 paymentResultInfo 中获取）。
- 额外支付验证信息字段（例如巴西卡的 cpf 字段）。
- isCardOnFile: 值为 true，用于标记该笔交易为绑卡买家的再次交易。
以下示例展示了绑卡用户再次支付时，使用 APO 返回的卡令牌调用 支付 接口的请求：
copy
{
"settlementStrategy": {
"settlementCurrency": "EUR"
},
"productCode": "CASHIER_PAYMENT",
"paymentNotifyUrl": "http://gol.alipay.net:8080/amsdemo/record/notify?env=main_GROUP&paymentMethodType=CARD",
"paymentRequestId": "2****************2",
"paymentRedirectUrl": "http://gol.alipay.net:8080/amsdemo/result?paymentRequestId=2023070471913565376977",
"paymentFactor": {
"isAuthorization": true
},
"paymentMethod": {
"paymentMethodId": "A********************************************************************************************=",
"paymentMethodMetaData": {
"recurringType": "SCHEDULED",
"is3DSAuthentication": false,
"isCardOnFile": true,
"networkTransactionId": "2*************5"
},
"paymentMethodType": "CARD"
},
"paymentExpiryTime": "2025-11-27T12:00:01+08:30",
"paymentAmount": {
"currency": "EUR",
"value": "3063"
},
"merchantRegion": "",
"order": {
"orderAmount": {
"currency": "EUR",
"value": "3063"
},
"referenceOrderId": "2****************1",
"shipping": {
"shippingName": {
"firstName": "Li",
"lastName": "Kyle",
"fullName": "Kyle Li"
},
"shippingCarrier": "DHL",
"shippingPhoneNo": "**********119",
"shipToEmail": "exam***@163.com",
"shippingAddress": {
"zipCode": "310000",
"address2": "gongzhuan Road",
"city": "hangzhou",
"state": "zhejiang",
"region": "CN"
}
},
"goods": [
{
"referenceGoodsId": "2********************9",
"goodsUrl": "qinghailipipeng",
"goodsCategory": "chemical",
"goodsUnitAmount": {
"currency": "EUR",
"value": "3063"
},
"goodsQuantity": "1",
"goodsName": "boom",
"goodsSkuName": "boom boom room",
"goodsBrand": "antom boom"
}
],
"env": {
"clientIp": "1.1.1.1",
"osType": "IOS",
"terminalType": "WAP"
},
"orderDescription": "ANTOM_ZZ",
"buyer": {
"referenceBuyerId": "K*****************3",
"buyerName": {
"firstName": "Li",
"lastName": "Kyle",
"fullName": "Kyle Li"
}
}
}
}SDK 集成方式
此方式下，SDK 为您的买家提供信息收集页面，在该页面上买家完成卡信息输入后，可选择保存卡信息，以便再次支付时无需重复输入卡信息。当买家选择保存卡信息后，APO 存储买家的卡信息并生成对应的卡令牌（cardToken) 。授权支付成功后，您可以通过接收异步通知或主动调用 支付结果查询 接口，获取买家的卡支付信息（cardInfo 字段），该信息包括卡令牌（cardToken) 及脱敏后的卡信息。
当绑卡用户再次进行支付时，您需要在调用 支付会话创建 请求时设置 paymentMethodId 参数值为 cardToken 的值。以下示例展示了绑卡用户再次支付时，您的服务端调用 支付会话创建 接口的请求示例：
copy
{
"productCode": "CASHIER_PAYMENT",
"paymentRequestId": "55bf93a6-71a1-4ca9-b014-53273bd674eb",
"order": {
"referenceOrderId": "926e1c32-4a6c-442e-b5ce-8ec5b902e18c",
"orderDescription": "xxxxx",
"orderAmount": {
"currency": "BRL",
"value": "100"
},
"buyer": {
"referenceBuyerId": "yeiasdasda",
"buyerPhoneNo": "134******71"
}
},
"paymentAmount": {
"currency": "BRL",
"value": "100"
},
"paymentMethod": {
"paymentMethodType": "CARD",
"paymentMethodId": "alipayCardToken"
},
"paymentRedirectUrl": "https://www.yourMerchantWeb.com",
"paymentNotifyUrl": "https://www.yourNotifyUrl",
"paymentFactor": {
"isAuthorization": true
},
"settlementStrategy": {
"settlementCurrency": "EUR"
}
}MIT 交易
卡授权支付场景下的自动扣款交易，也被称为Merchant-initiated Transactions (MIT) 交易，即在用户未参与的情况下发起定期或非定期的交易。
注意：
- 此场景下的交易均为非 3D 验证的交易。
- 发起并完成 MIT 交易的前提是您已经获取了买家的授权以完成后续的 MIT 交易，买家需在首次授权支付时完成 3D 验证。
MIT 交易仅支持通过 支付 接口完成，请注意以下参数的设置：
- isCardOnFile: 值为
true，用于标记该笔交易为绑卡买家的再次支付。 - recurringType：值为
SCHEDULED或UNSCHEDULED， 用于指定该笔交易为定期扣款或非定期扣款。 - networkTransactionId：系统需要确认您已经获取了买家的授权以完成后续的 MIT 交易，因此，您需要通过此字段传入买家进行初始授权支付时卡组分配的用于识别授权支付交易的唯一 ID。当买家首次授权支付成功后，您通过 支付结果通知 或 查询支付结果 请求的响应均可以获得该授权支付交易唯一 ID。
API 集成方式下，服务器对服务器模式及托管表单模式均支持自动扣款功能。以下示例以服务器对服务器模式为例，展示调用 支付 接口发起 MIT 交易的请求示例：
copy
{
"env": {
"browserInfo": {
"acceptHeader": "*/*",
"javaEnabled": true,
"javaScriptEnabled": true,
"language": "zh_CN",
"userAgent": "Chrome/100"
},
"terminalType": "APP",
"clientIp": "112.80.248.78",
"deviceId": "eYOIkvFpZzztgO0Yu6USdprBQZCWxDhiUAHCiK8K/cH9mT6wMaMOzAKe",
"osType": "IOS",
"deviceLanguage": "zh_CN",
"colorDepth": 48,
"screenHeight": 768,
"screenWidth": 1024,
"timeZoneOffset": 1
},
"order": {
"orderAmount": {
"currency": "EUR",
"value": "30000"
},
"orderDescription": "Cappuccino #grande (Mika's coffee shop)",
"referenceOrderId": "ORDER_20221114141714891",
"goods": [
{
"referenceGoodsId": "383382011_SGAMZ-904520356",
"goodsName": "[3 Boxes] Starbucks Cappuccino Milk Coffee Pods / Coffee Capsules by Nescafe Dolce Gusto",
"goodsUrl": "https://www.lazada.sg/products/3-boxes-starbucks-cappuccino-milk-coffee-pods-coffee-capsules-by-nescafe-dolce-gusto-i383382011-s904520356.html?clickTrackInfo=undefined&search=1&source=search&spm=a2o42.searchlist.list.3",
"goodsCategory": "Digital Goods/Digital Vouchers/Food and Beverages",
"goodsUnitAmount": {
"currency": "EUR",
"value": "30000"
},
"goodsQuantity": "10"
}
],
"shipping": {
"shippingName": {
"firstName": "Dehua",
"lastName": "Liu",
"fullName": "Dehua Skr Liu",
"middleName": "Skr"
},
"shippingAddress": {
"zipCode": "310000",
"address2": "Xihu",
"city": "Hangzhou",
"address1": "Wuchang road",
"state": "Zhejiang",
"region": "CN"
},
"shippingCarrier": "FedEx",
"shippingPhoneNo": "12345678912",
"shipToEmail": "test@gmail.com"
},
"buyer": {
"referenceBuyerId": "test12345678",
"buyerPhoneNo": "12345678912",
"buyerEmail": "alipay@alipay.com",
"buyerName": {
"firstName": "Dehua",
"lastName": "Liu",
"fullName": "Dehua Skr Liu",
"middleName": "Skr"
}
}
},
"paymentAmount": {
"currency": "EUR",
"value": "30000"
},
"paymentMethod": {
"paymentMethodType": "CARD",
"paymentMethodMetaData": {
"isCardOnFile": true,
"recurringType": "SCHEDULED",
"networkTransactionId": "referenceNetworkTransactionId12345",
"enableAuthenticationUpgrade": false,
""is3DSAuthentication": false,
"cvv": "850",
"cardholderName": {
"firstName": "Tom",
"lastName": "Jay"
},
"expiryMonth": "12",
"billingAddress": {
"zipCode": "310000",
"address2": "Xihu",
"city": "Hangzhou",
"address1": "Wuchang road",
"state": "Zhejiang",
"region": "CN"
},
"expiryYear": "29",
"cardNo": "4117347806156383"
}
},
"settlementStrategy": {
"settlementCurrency": "EUR"
},
"paymentNotifyUrl": "https://www.alipay.com/notify",
"paymentRedirectUrl": "https://www.alipay.com",
"paymentRequestId": "PAY_20221114141714891",
"productCode": "CASHIER_PAYMENT",
"paymentFactor": {
"isAuthorization": true
}
}MPI 功能
如果您在授权交易发起前优先让买家通过第三方 Merchant Plug-ins (MPI) 完成3D 核身校验，此时需要您在调用 支付 接口发起授权支付时，通过 mpiData 字段传入 3D 核身结果并指定指定交易为非 3D 认证：
字段 | 说明 |
mpiData.threeDSVersion | 传入第三方核身机构返回的 3D 协议版本号。 |
mpiData.caav | 传入第三方核身机构返回的 caav。 |
mpiData.dsTransactionId | 传入第三方核身机构返回的交易唯一标识符。 |
mpiData.eci | 传入第三方核身机构返回的 ECI。 |
is3DSAuthentication | 传入 |
enableAuthenticationUpgrade | 传入 |
表 4. MPI 信息
您调用 支付 接口传入 mpiData 等关键信息的请求样例如下：
copy
{
"env": {
"browserInfo": {
"acceptHeader": "*/*",
"javaEnabled": true,
"javaScriptEnabled": true,
"language": "zh_CN",
"userAgent": "Chrome/100"
},
"terminalType": "APP",
"clientIp": "112.80.248.78",
"deviceId": "e******************************************1",
"osType": "IOS",
"deviceLanguage": "zh_CN",
"colorDepth": 48,
"screenHeight": 768,
"screenWidth": 1024,
"timeZoneOffset": 1
},
"order": {
"orderAmount": {
"currency": "EUR",
"value": "30000"
},
"orderDescription": "Cappuccino #grande (Mika's coffee shop)",
"referenceOrderId": "O*******************1",
"goods": [
{
"referenceGoodsId": "383382011_SGAMZ-90452****",
"goodsName": "[3 Boxes] Starbucks Cappuccino Milk Coffee Pods / Coffee Capsules by Nescafe Dolce Gusto",
"goodsUrl": "https://www.lazada.sg/products/3-boxes-starbucks-cappuccino-milk-coffee-pods-coffee-capsules-by-nescafe-dolce-gusto-i383382011-s904520356.html?clickTrackInfo=undefined&search=1&source=search&spm=a2o42.searchlist.list.3",
"goodsCategory": "Digital Goods/Digital Vouchers/Food and Beverages",
"goodsUnitAmount": {
"currency": "EUR",
"value": "30000"
},
"goodsQuantity": "10"
}
],
"shipping": {
"shippingName": {
"firstName": "Dehua",
"lastName": "Liu",
"fullName": "Dehua Skr Liu",
"middleName": "Skr"
},
"shippingAddress": {
"zipCode": "310000",
"address2": "Xihu",
"city": "Hangzhou",
"address1": "Wuchang road",
"state": "Zhejiang",
"region": "CN"
},
"shippingCarrier": "FedEx",
"shippingPhoneNo": "1234567****",
"shipToEmail": "test***@gmail.com"
},
"buyer": {
"referenceBuyerId": "t**********4",
"buyerPhoneNo": "********567",
"buyerEmail": "exam***@alipay.com",
"buyerName": {
"firstName": "D****",
"lastName": "L****",
"fullName": "Dehua Skr****",
"middleName": "S****"
}
}
},
"paymentAmount": {
"currency": "EUR",
"value": "30000"
},
"paymentMethod": {
"paymentMethodType": "CARD",
"paymentMethodMetaData": {
"isCardOnFile": false,
"enableAuthenticationUpgrade": false,
"is3DSAuthentication": false,
"mpiData": {
"eci": "02",
"threeDSVersion": "2.2.0",
"caav": "cavvSample",
"dsTransactionId": "sample_dsTranascti****"
},
"cvv": "850",
"cardholderName": {
"firstName": "Tom",
"lastName": "Jay"
},
"expiryMonth": "12",
"billingAddress": {
"zipCode": "310000",
"address2": "Xihu",
"city": "Hangzhou",
"address1": "Wuchang road",
"state": "Zhejiang",
"region": "CN"
},
"expiryYear": "29",
"cardNo": "****0615"
}
},
"settlementStrategy": {
"settlementCurrency": "EUR"
},
"paymentNotifyUrl": "https://www.alipay.com/notify",
"paymentRedirectUrl": "https://www.alipay.com",
"paymentRequestId": "P*******************1",
"productCode": "CASHIER_PAYMENT",
"paymentFactor": {
"isAuthorization": true
}
}您调用 支付会话创建 接口传入 mpiData 等关键信息的请求样例如下：
copy
{
"env": {
"clientIp": "112.80.248.78"
},
"order": {
"orderAmount": {
"currency": "EUR",
"value": "30000"
},
"orderDescription": "Cappuccino #grande (Mika's coffee shop)",
"referenceOrderId": "O********************1",
"goods": [
{
"referenceGoodsId": "3********************2",
"goodsName": "[3 Boxes] Starbucks Cappuccino Milk Coffee Pods / Coffee Capsules by Nescafe Dolce Gusto",
"goodsUrl": "https://www.lazada.sg/products/3-boxes-starbucks-cappuccino-milk-coffee-pods-coffee-capsules-by-nescafe-dolce-gusto-i383382011-s904520356.html?clickTrackInfo=undefined&search=1&source=search&spm=a2o42.searchlist.list.3",
"goodsCategory": "Digital Goods/Digital Vouchers/Food and Beverages",
"goodsUnitAmount": {
"currency": "EUR",
"value": "30000"
},
"goodsQuantity": "10"
}
],
"shipping": {
"shippingName": {
"firstName": "Dehua",
"lastName": "Liu",
"fullName": "Dehua Skr Liu",
"middleName": "Skr"
},
"shippingAddress": {
"zipCode": "310000",
"address2": "Xihu",
"city": "Hangzhou",
"address1": "Wuchang road",
"state": "Zhejiang",
"region": "CN"
},
"shippingCarrier": "FedEx",
"shippingPhoneNo": "1234567****",
"shipToEmail": "test@gmail.com"
},
"buyer": {
"referenceBuyerId": "test1234****",
"buyerPhoneNo": "1234567****",
"buyerEmail": "example@alipay.com",
"buyerName": {
"firstName": "D****",
"lastName": "L****",
"fullName": "Dehua Skr****",
"middleName": "S****"
}
}
},
"paymentAmount": {
"currency": "EUR",
"value": "30000"
},
"paymentMethod": {
"paymentMethodType": "CARD",
"paymentMethodMetaData": {
"isCardOnFile": false,
"enableAuthenticationUpgrade": false,
"is3DSAuthentication": false,
"mpiData": {
"eci": "02",
"threeDSVersion": "2.2.0",
"caav": "cavvSample",
"dsTransactionId": "sample_dsTranascti****"
},
"cvv": "850",
"cardholderName": {
"firstName": "Tom",
"lastName": "Jay"
},
"expiryMonth": "12",
"billingAddress": {
"zipCode": "310000",
"address2": "Xihu",
"city": "Hangzhou",
"address1": "Wuchang road",
"state": "Zhejiang",
"region": "CN"
},
"expiryYear": "29",
"cardNo": "****0615"
}
},