Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

Value-added features

After you initiate an authorized payment, you can choose whether to use value-added features based on your service needs. This topic explains the value-added features and how to use them.

Set 3D verification

You can choose whether to subject a payment to 3D verification by specifying the is3DSAuthentication parameter.

  • Leave is3DSAuthentication empty: The result is the same as that of specifying the parameter as false. 3D verification is disabled for the payment. If Alipay determines this payment as high-risk, this payment is rejected.
  • Specify is3DSAuthentication as false: 3D verification is disabled for the payment. If Alipay determines this payment as high-risk, this payment is rejected.
  • Specify is3DSAuthentication as true: 3D verification is enabled for the payment. If Alipay determines this payment as high-risk, this payment is rejected.

Note:

  • For API integration, specify this parameter in the pay API. For SDK integration, specify this parameter in the createPaymentSession API.
  • This feature is unavailable for payments initiated using South Korean cards under any South Korean card scheme.

Intelligent transaction salvage

The transaction salvage feature allows transactions where the card scheme requires 3D verification to automatically initiate the 3D verification process. This enables you to salvage transactions regardless of whether you previously chose 3D verification for them.

You can enable the transaction salvage feature for a transaction by specifying enableAuthenticationUpgrade as true. If you do not enable this feature and 3D verification for a transaction where the card scheme requires 3D verification, the card scheme determines this transaction as risky and rejects the payment.

Note:

  • For API integration, specify this parameter in the pay API. For SDK integration, specify this parameter in the createPaymentSession API.
  • This feature is unavailable for payments initiated using certain cards under the corresponding local card scheme. These cards include Brazilian cards, South Korean cards, Singaporean cards, and Hong Kong cards.

Setting 3D verification and automatic transaction salvage will jointly determine the risk control verification process of transactions. The following table shows how the settings of the two features affect the risk control results:

Set 3D verification:

is3DSAuthentication

Set automatic transaction salvage: 

enableAuthenticationUpgrade

Risk control result

false/leave it empty

true/leave it empty

After a payment without 3D verification failed, this payment automatically triggers 3D verification, and Alipay returns the URL for rendering a 3D verification page.

false/leave it empty

false

If a payment without 3D verification failed, Alipay returns the result of a failed payment.

true

true/false/leave it empty

This payment is to undergo 3D verification, and Alipay returns the URL for rendering a 3D verification page.

Table 1. Risk control result affected by the settings of the two features

For SDK integration, the SDK handles the redirection to the 3D verification page, requiring no extra effort on your part. For API integration, after Alipay returns the URL for rendering a 3D verification page, you need to display the verification page and guide buyers to finish the verification process. The following code sample shows how the URL is returned through the response in the pay API:

copy
{
  "result": {
    "resultStatus": "U",
    "resultCode": "PAYMENT_IN_PROCESS",
    "resultMessage": "payment in process"
  },
  "normalUrl": "https://centinelapi.cardinalcommerce.com/V1/Cruise/Collect/...",
  "paymentId": "20221111194010890100111650285726898",
  "paymentRequestId": "amsdmpay_cangxi_lj_20221111_104718_672",
  "redirectActionForm": {
    "redirectUrl": "https://centinelapi.cardinalcommerce.com/V1/Cruise/Collect/...",
    "method": "GET"
  },
  "paymentAmount": {
    "currency": "HKD",
    "value": "100"
  },
  "paymentCreateTime": "2022-11-10T18:47:20-08:00"
}

Value-added risk control service

If you need an upgraded risk control service for payments, you can purchase the value-added risk control service provided by Alipay. This service provides intelligent risk control policies based on the risk levels of payments.

Setting 3D verification, automatic transaction salvage, and this feature will jointly determine the risk control verification process of transactions. The following table shows how the settings of the three features affects the risk control results:

Value-added risk control service

Set 3D verification:

is3DSAuthentication

Set automatic transaction salvage: 

enableAuthenticationUpgrade

Risk control result

Enabled

false/leave it empty

false

The risk control service determines whether to execute 3D verification.

Enabled

false/leave it empty

true/leave it empty

The risk control service determines whether to execute 3D verification. If the service determines not to execute 3D verification and a card scheme requires 3D verification, Alipay returns the URL for rendering a 3D verification page.

Enabled

true

true/false/leave it empty

Even if the risk control service determines not to execute 3D verification, Alipay returns the URL for rendering a 3D verification page.

Table 2. Risk control result affected by settings of the three features

Note：

  • If you have purchased the value-added risk control service, you do not need to specify the is3DSAuthentication parameter. The risk control service provides you with risk control policies.
  • This feature is unavailable for payments initiated using certain cards under the supervision of the corresponding local card scheme. These cards include Brazilian cards, South Korean cards, Singaporean cards, and Hong Kong cards.

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 in order 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, you can initiate an AVS check based on your integration mode:

  • For API integration:
    • If you use server-to-server communication, pass in the billingAddress parameter through the pay API.
    • If you use the form hosting service, Alipay provides the payment information collection page for buyers to enter their billing address, requiring no extra effort on your part.
  • For SDK integration, the SDK provides buyers with the payment information collection page for buyers to enter their billing address, requiring no extra effort on your part.

Note:

  • You can obtain the result of the AVS check through the avsResultRaw parameter in the response of the notifyPayment or inquiryPayment API.
  • This feature is only available for payments initiated using American cards under the supervision of American card schemes.

Card information storage

You can allow buyers to add their cards. That is, users can choose to save their card information during the first-time 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 saved their card information during the first-time payment.

image

Figure 1. Checkout page for subsequent payment with previously saved card information

API integration

How to add users' cards varies by integration mode. For server-to-server mode and form-hosting mode, perform these steps accordingly:

When a buyer chooses to save their card on your page, you need to store the buyer information and the corresponding card information on your server. When the buyer makes a subsequent payment, you need to pass in the card information through the pay API and specify the isCardOnFile parameter as true. This parameter is used to label this payment as a subsequent payment using a saved card, thus boosting payment success rates.

The following code sample shows how your server calls the pay API when a buyer makes a subsequent payment using a saved card:

copy
{
    "env": {
        "terminalType": "APP",
        "clientIp": "112.80.248.78",
        "deviceId": "eYOIkvFpZzztgO0Yu6USdprBQZCWxDhiUAHCiK8K/cH9mT6wMaMO****",
        "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_2022111414171****",
        "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": "test12345678",
            "buyerPhoneNo": "1234567****",
            "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,
            "enableAuthenticationUpgrade": false,
            "is3DSAuthentication": false,
            "cardholderName": {
                "firstName": "Tom",
                "lastName": "Jay"
            },
            "expiryMonth": "12",
            "billingAddress": {
                "zipCode": "310000",
                "address2": "Xihu",
                "city": "Hangzhou",
                "address1": "Wuchang road",
                "state": "Zhejiang",
                "region": "CN"
            },
            "expiryYear": "29",
            "cardNo": "411734780615****"
        }
    },
    "settlementStrategy": {
        "settlementCurrency": "EUR"
    },
    "paymentNotifyUrl": "https://www.alipay.com/notify",
    "paymentRedirectUrl": "https://www.alipay.com",
    "paymentRequestId": "PAY_2022111414171****",
    "productCode": "CASHIER_PAYMENT",
    "paymentFactor": {
        "isAuthorization": true
    }
}

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, Alipay 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:

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 Transaction (MIT) refers to a type of pre-authorized transactions for card payments, that is, regular or irregular transactions without the buyer's participation.

Note：

  • MIT is a type of transactions 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.
  • This feature is unavailable for payments initiated using certain cards under the corresponding local card scheme. These cards include Brazilian cards, South Korean cards, Singaporean cards, and Hong Kong cards.

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 SCHEDULED or UNSCHEDULED, which is used to specify this payment as a regular or irregular payment.
  • networkTransactionId: Alipay 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-time authorization. When the buyer completes the payment with the first-time 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:

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
    }
}

Specify a card brand

When a buyer chooses a dual-scheme card (a card issued under two card schemes) for an authorized payment, you can specify the card brand and region by specifying the paymentMethodRegion and selectedCardBrands parameters. The following table shows how the settings of the two parameters determines the card brand for the payment:

PaymentMethodRegion

selectCardBrands

Card brand for the payment

GLOBAL

/

A global card brand

FR, BR..

/

A local card brand

/

VISA, CB

A specific card brand

/

/

A card brand determined by Alipay considering the costs and success rates

Table 3. Card brand determined by the settings of the two parameters

Note:

  • For the card brand and region of a specific card, see Payment methods。
  • This feature is unavailable for payments initiated using Brazilian cards under any Brazilian card scheme.