API integration

2023-05-30 08:20

The API integration introduces how to initiate an authorized payment via APIs. This integration method is suitable for merchants who have high requirements for customization in the payment process.

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 the value-added 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:

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 and store the user's card information, environment information, and order information.
Call the pay API to request an authorization payment.
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.
Display the authorization payment result to the buyer.

6@3x.png

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

User experience

First payment (Web)

First payment (App)

Saved card payment (Web)

Saved card payment (App)

API call

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

Card info

Env info: used to improve the payment success rate

Order info: used to reduce payment rejection and card theft rates

cardNo

cvv

expiryYear

expiryMonth

cardholderName

billingAddress

...

browserInfo

clientIp

terminalType

goods

shipping

buyer

Table 1. Card information to be collected

When sending a request for the pay API, you can also choose to use the following value-added features according to your business needs.

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.

For more information about how to use the value-added features, see Value-added features.

The request sample of the pay API:

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": 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 card token (cardToken) for subsequent payments.

Integration steps

In the hosted payment page mode, follow the steps to complete an authorization payment:

The buyer selects the card payment method and goes to pay.
Call the pay API to submit the authorization payment request. The card information is not included in the API request.
After Alipay receives the API call request, a card information collection page is returned for the buyer to enter the card information.
Open an intermediate page on the front end to display the card information collection page for the buyer.
After the buyer enters complete payment information, Alipay verifies the payment information. When the verification is successful, Alipay processes the API call with the payment information stored as a token (cardToken) and submits the authorization payment request to the card issuer.
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.
Display the result of the authorization payment to the buyer.

7@3x.png

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

User experience

First payment (Web)

First payment (App)

Saved card payment (Web)

Saved card payment (App)

API call

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

Env info: used to improve the payment success rate

Order info: used to reduce payment rejection and card theft rates

terminalType

goods

shipping

buyer

Table 2. Information to be collected

When sending a request for the pay API, you can also choose to use the following value-added features according to your business needs.

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.

For more information about how to use the value-added features, see Value-added features.

The request sample of the pay API:

copy
{
    "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.

8@3x.png

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.

The following code samples show the response you may receive after calling the pay API. The response may include information on successful authorization payments, failed authorization payments, or redirect URLs for authorization payments in the process:

Authorization payment successful

Authorization payment failed

Authorization in the process

copy
{
    "paymentAmount": {
        "currency": "EUR",
        "value": "1314"
    },
    "paymentCreateTime": "2021-11-12T01:27:50-08:00",
    "paymentId": "20211112194010800100188570271832381",
    "paymentRequestId": "PAY_20211112172747856",
    "paymentResultInfo": {
        "avsResultRaw": "A",
        "cvvResultRaw": "Y",
        "networkTransactionId": "sampleNetworkTransactionId123456"
    },
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success.",
        "resultStatus": "S"
    }
}

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:

API	Authorization result	AVS info	CVV info	3DS authentication info
notifyPayment	resultStatus	avsResultRaw	cvvResultRaw	threeDSResult (only available for the 3DS authentication authorization)
inquiryPayment	paymentStatus	avsResultRaw	cvvResultRaw	threeDSResult (only available for the 3DS authentication authorization)

Figure 3. Key information about the authorization result

The following code samples show the result returned by noitfyPayment and inquiryPayment:

notifyPayment (3D)

notifyPayment (non-3D)

inquiryPayment (3D)

inquiryPayment (non-3D)

copy
{
    "notifyType": "PAYMENT_RESULT",
    "result": {
        "resultCode": "SUCCESS",
        "resultStatus": "S",
        "resultMessage": "success"
    },
    "paymentRequestId": "2020010123456789XXXX",
    "paymentId": "2020010123456789XXXX",
    "paymentAmount": {
        "value": "8000",
        "currency": "EUR"
    },
    "paymentCreateTime": "2020-01-01T12:01:00+08:30",
    "paymentTime": "2020-01-01T12:01:01+08:30",
    "paymentResultInfo": {
        "avsResultRaw": "A",
        "cvvResultRaw": "Y",
        "networkTransactionId": "sampleNetworkTransactionId123456",
        "threeDSResult": {
            "eci": "02",
            "threeDSVersion": "2.2.0",
            "caav": "cavvSample",
            "dsTransactionId": "sample_dsTranasctionId"
        }
    }
}