More features
When initiating an authorized payment, you can choose whether to use more features based on your service needs. This topic explains the more features and how to use them.
Set 3D verification
You can choose whether to subject payment to 3D verification by specifying the is3DSAuthentication parameter.
- Specify is3DSAuthentication as
true: 3D verification is enabled for the payment. - Specify is3DSAuthentication as
false: The acquirer will decide whether to trigger 3D verification. If you have access to Ant Independent Risk Control, it will prioritize whether to trigger 3D verification. - Leave is3DSAuthentication empty: The result is the same as that of specifying the parameter as false. The acquirer will decide whether to trigger 3D verification. If you have access to Ant Independent Risk Control, it will prioritize whether to trigger 3D verification.
For API integration, specify this parameter in the pay API. For SDK integration, specify this parameter in the createPaymentSession API.
AVS check
An address verification system (AVS) check compares the billing address used in the transaction with the issuing bank's address information on file for that cardholder to detect fraud. By enabling the AVS check, the system automatically compares the billing address and email address entered by a buyer with the issuer's stored information. If there is a mismatch between this information, it may lead to a payment rejection or extra identity verification.
After you enable the AVS check service, APO supports you to initiate AVS verification in the following ways based on your integration mode:
- For API integration:
- Pass in the billingAddress parameter through the pay API.
- For SDK integration:
- You can contact technical support to configure the buyer billing address collection box under the payment information collection page provided by the SDK for buyers.
- You can also choose to pass in the billing information collected in advance yourself and pass in the billingAddress parameter in the createPaymentSession API to initiate AVS verification. The Web/WAP side, meanwhile, supports you to pass in the billingAddress parameter through the
submitmethod of the SDK.
You can obtain the result of the AVS check through the avsResultRaw parameter in the response of the notifyPayment or inquiryPayment API.
Card information storage
You can allow buyers to add their cards. That is, users can choose to save their card information during the first payment so that they do not need to re-enter the information for subsequent payments. The following figure shows the checkout page for a subsequent payment after a user saves their card information during the first payment.
Figure 1. Checkout page for subsequent payment with previously saved card information
API integration
In API integration mode, after collecting the buyer's card information, you can choose to store the card information yourself or let APO store it for you.
When a buyer stores card information on your page, pass in the card information to APO through the pay API and specify the tokenize field as true. APO generates a corresponding card token (cardToken) for the card information. After the payment is authorized successfully, obtain the card token (cardToken) and the masked card number (cardNo) by receiving an asynchronous notification or calling the inquiryPayment API. To process subsequent payments, you must store and associate the obtained card token, masked card number, and other information concerning the buyer.
The following code sample shows the pay API call request when APO stores card information after you collect the card information:
{
"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"
}
}
}
}When a buyer makes a payment using a saved card, complete the following:
- Display the masked card information for the buyer on the checkout page.
- Pass in the following parameters through the pay API:
- paymentMethodId: The value is the same as that of the cardToken parameter (obtained from paymentResultInfo of notifyPayment and inquiryPayment).
- Extra verification parameters (such as the cpf parameter for Brazilian cards).
- isCardOnFile: Set the value to true. This parameter is used to identify a subsequent payment using a saved card.
The following code sample shows the pay API call request using a card token when a buyer uses a saved card to pay:
{
"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 integration
In this integration mode, the SDK provides a payment information collection page. A buyer enters their card information and chooses to save the information, so that they do not need to re-enter the information for subsequent payments. When a buyer chooses to save their card information, APO stores the information and generates a corresponding card token (cardToken). After this payment is authorized, you can obtain the buyer's card information (cardInfo) by receiving an asynchronous notification or calling the inquiryPayment API. The card information includes the card token (cardToken) and the desensitized card information.
When a buyer makes a subsequent payment using a saved card, you need to specify paymentMethodId as the value of cardToken when calling the createPaymentSession API. The following code sample shows how your server calls the createPaymentSession API when a buyer makes a subsequent payment using a saved card:
{
"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 Transaction (MIT) refers to a type of pre-authorized transaction for card payments, that is, regular or irregular transactions without the buyer's participation.
Notes:
- MIT is a type of transaction without 3D verification.
- Before you initiate an MIT, you must obtain a buyer's authorization, which requires the buyer to complete 3D verification for the first-time authorization of the payment.
For API integration, specify the following parameters in the pay API to initiate an MIT. For SDK integration, specify the following parameters in the createPaymentSession API to initiate an MIT.
- isCardOnFile: The value is
true, which is used to label the payment as a subsequent payment using a saved card. - recurringType: The value is
SCHEDULEDorUNSCHEDULED, which is used to specify this payment as a regular or irregular payment. - networkTransactionId: APO needs to confirm that you have obtained the buyer authorization to complete the MIT. Therefore, you must pass in a unique identifier to this parameter. The identifier is assigned by a card scheme to identify an authorized payment for the first authorization. When the buyer completes the payment with the first authorization, you can obtain the identifier through the response in the notifyPayment API or inquiryPayment API.
In API integration mode, automatic deduction is supported for the server-to-server mode and form-hosting mode. The following code sample shows how your server calls the pay API to initiate an MIT in the server-to-server mode:
{
"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
If you let your buyer complete 3D Secure authentication through a third party before you initiate the authorized payment, pass in the 3D Secure authentication result through mpiData and specify this payment as non-3D Secure authentication when calling the pay API.
Field | Description |
mpiData.threeDSVersion | The 3D Secure protocol version returned by the third-party authentication agency. |
mpiData.caav | The cardholder authentication value returned by the third-party authentication agency. |
mpiData.dsTransactionId | The unique transaction identifier returned by the third-party authentication agency. |
mpiData.eci | Electronic Commerce Indicator (ECI) returned by the third-party authentication agency. |
is3DSAuthentication | Set to |
enableAuthenticationUpgrade | Set to |
Figure 4. MPI (Merchant Plug-in) information
The following code sample shows the request for calling the pay API with mpiData:
{
"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
}
}The following code sample shows the request for calling the createPaymentSession API with mpiData:
{
"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"
}
},