The API integration introduces how to initiate an authorized payment via APIs.

Request for an authorization payment

After the buyer clicks the button to pay, you need to call the pay API (POST/v1/payments/pay) to initiate an authorization for a card payment. Perform this step according to the following instructions:

• After the buyer clicks to pay, disable the payment button until you receive the API result in case of repeated operations triggered by the user.
• You can collect card information and initiate an authorization payment in the following two ways:

• Server-to-server mode: This mode requires that you are PCI qualified.
• Hosted payment page mode: This mode does not require that you are PCI qualified.

• You can also choose to use More features according to your business needs when initiating an authorization payment.

Server-to-server mode

Server-to-server payment mode allows you to process transactions by sending requests from your server to the Alipay server. With this integration mode, you need to provide all user information, including card payment information.

Prerequisites for integration

The server-to-server integration mode requires that you are PCI qualified. Provide the following materials to complete verification according to business requirements:

• If your annual card transaction volume is expected to exceed 6 million, complete and submit the PCI Attestation of Compliance (AoC) file for verification.
• If your annual card transaction volume is expected to be below 6 million, complete and submit the PCI DSS Self-Assessment Questionnaires (SAQs) file for verification.

For more information about PCI DSS compliance requirements, see PCI DSS standard.

Integration steps

In the server-to-serve mode, follow the steps to complete an authorization payment:

1. After the buyer chooses the car payment method, display the card information collection page for the buyer (this page is developed by you). During this process, you need to collect the user's card information, environment information, and order information.
2. Call the pay API to request an authorization payment.
3. Process the response of the pay API. The response may contain the result of the authorization payment. For more information about how to handle the response, see Obtain authorization result.
4. Display the authorization payment result to the buyer.

Figure 1. The interaction process of authorization payment (Server-to-server mode)

User experience

API call

When sending a request for the pay API (POST/v1/payments/pay), you need to provide the following information:

Table 1. Card information to be collected

When sending a request for the pay API, you can also choose to use the following features according to your business needs. Please refer to More features for details about how to use more features.

• Enable 3D authentication: Specify the value of is3DSAuthentication in the pay API to set whether the transaction is authenticated by using 3D Secure.
• Salvage transaction intelligently: Automatically initiate a 3D Secure authentication for a non-3D Secure transaction if required by the card issuer to salvage a failed transaction. Specify the enableAuthenticationUpgrate parameter in the pay API to enable this feature.
• Value-added risk control services: Alipay provides upgraded risk control services at a transaction level, and intelligently decides risk control strategies based on the risk level of a transaction.
• Address Verification System (AVS) service: This service verifies whether the provided billing address matches the cardholder's address on record at the issuing bank. AVS helps to prevent fraudulent transactions.
• Store card info: Obtain the buyer's agreement to store card information at the first payment, so that the card information does not need to be entered again for the next payment.
• Merchant-initiated transactions (MIT): Initiate scheduled or unscheduled transactions without user involvement.
• Specify card brand: For dual-branded card payments, specify the brand or region of the card used for authorization.
• Merchant Plug-In (MPI): If the buyer completes 3D Secure authentication through a third-party authentication agency before the payment, pass in the 3D Secure authentication result when calling the pay API. The MPI feature is only available if you collect the buyer's card information.

The request sample of the pay API:

{
    "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": false,
            "enableAuthenticationUpgrade": true,
            "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
    }
}

Hosted payment page mode

The hosted payment page mode protects you from PCI-DSS restrictions because sensitive data (such as card no. and password) is not transmitted through your server, so PCI qualification is not required. In this mode, Alipay provides the payment information collection page and collects payment information. The payment information is then stored as a cardToken for subsequent payments.

Integration steps

1. Buyer selects a payment method and clicks the Pay button.
2. Call the pay API to request an authorization payment. Card information is not included in this API request.
3. Alipay receives the API call request and returns the card information collection page for the buyer to enter card information.
4. Open an intermediate page on the front-end page to show the card information collection page to the buyer.
5. After the buyer fills in the complete payment element information, Alipay validates the payment element. Once validated, Alipay advances the API call and stores the payment element information as a cardToken, and submits an authorization request to the card group.
6. Alipay returns a response to your request, which may contain the authorization payment result. Please refer to Obtain authorization result for more details about how to handle the response.
7. Display the authorization payment result.

Figure 2. The interaction process of authorization payment (Hosted payment page mode)

User experience

API call

When sending a request for the pay API (POST/v1/payments/pay), you need to provide the following information:

Table 2. Information to be collected

When sending a request for the pay API, you can also choose to use the following features according to your business needs. Please refer to More features for details about how to use more features.

• Enable 3D authentication: Specify the value of is3DSAuthentication in the pay API to set whether the transaction is authenticated by using 3D Secure.
• Salvage transaction intelligently: Automatically initiate a 3D Secure authentication for a non-3D Secure transaction if required by the card issuer to salvage a failed transaction. Specify the enableAuthenticationUpgrate parameter in the pay API to enable this feature.
• Value-added risk control services: Alipay provides upgraded risk control services at a transaction level, and intelligently decides risk control strategies based on the risk level of a transaction.
• Address Verification System (AVS) service: This service verifies whether the provided billing address matches the cardholder's address on record at the issuing bank. AVS helps to prevent fraudulent transactions.
• Store card info: Obtain the buyer's agreement to store card information at the first payment, so that the card information does not need to be entered again for the next payment.
• Merchant-initiated transactions (MIT): Initiate scheduled or unscheduled transactions without user involvement.

The request sample of the pay API:

{
    "env": {
        "terminalType": "APP",
        "clientIp": "112.80.248.78",
        "deviceId": "eYOIkvFpZzztgO0Yu6USdprBQZCWxDhiUAHCiK8K/cH9mT6wMaMOzAKe",
        "osType": "IOS",
        "deviceLanguage": "zh_CN"
    },
    "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"
    },
    "settlementStrategy": {
        "settlementCurrency": "EUR"
    },
    "paymentNotifyUrl": "https://www.alipay.com/notify",
    "paymentRedirectUrl": "https://www.alipay.com",
    "paymentRequestId": "PAY_20221114141714891",
    "productCode": "CASHIER_PAYMENT",
    "paymentFactor": {
        "isAuthorization": true
    }
}

In subsequent payments after the buyer saved a card in the first card payment, you need to pass in the obtained cardToken information through the paymentMethod.paymentMethodId parameter in the pay API. The value of cardToken can be obtained in the following ways:

• Receive asynchronous notification (notifyPayment): cardToken is in the cardInfo object in the notification.
• Call the inquiryPayment API: cardToken is in the cardInfo object returned by the inquiryPayment API.

Obtain authorization result

After calling the pay API, the value of the resultStatus parameter in the response returned by Alipay indicates the authorization payment result of a transaction.

Figure 3. Descriptions of resultStatus in response

• S(resultStatus): indicates that the authorization payment is successful.
• F(resultStatus): indicates that the authorization payment is failed.
• U(resultStatus) and PAYMENT_IN_PROCESS (resultCode): indicates that the authorization payment is in progress and your buyer needs to be redirected to the URL specified in the normalUrl parameter to complete the authorization payment. You can obtain the result of the authorization payment through asynchronous notifications or inquire through inquiryPayment.

Note: In the hosted payment page mode, the value of the resultStatus parameter returned by the pay API can only be F or U.

Receive an asynchronous notification

You can obtain the authorization result by receiving an asynchronous notification sent by Alipay. You must set a notification address before you can receive the asynchronous notification. When a final authorization status is achieved (that is, when the authorization is successful or failed), Alipay sends you the asynchronous notification through notifyPayment. When you receive the notification, you must return a response as instructed in Requirements. Otherwise, Alipay resends the notification until a correct response is received.

Inquire about the authorization result

Due to network issues, asynchronous notifications may not be delivered or may be delayed. Therefore, we recommend that you proactively query the transaction status through the inquiryPayment (POST/v1/payments/inquiryPayment) API. You can set up active queries in the following scenarios:

• Before the payment result page is invoked: When the payment is initiated on the payment method page, you can automatically trigger calling the inquiryPayment API for subsequent redirection.
• When the user inquires about the payment result: When the user clicks or taps I have paid or a button with the same meaning on your page, you can call the inquiryPayment API to check the payment status.
• When the payment expires: When the payment reaches the expiry time, you can call the inquiryPayment API to check the payment status.

The response obtained from asynchronous notifications and inquiryPayment contains the authorization payment result as well as other key information such as:

Table 3. Key information about the authorization result