Alipay enables you to receive payments by using various payment methods. One of the most popular payment methods is the card payment method, which has a different integration from that of other payment methods. This guide describes how to integrate the card payment method.

Prerequisites

Before you begin, you must complete the following tasks:

• Register on Alipay Developer Center.
• Set your keys.
• If you want to receive payments in Hong Kong or Singapore, contact Alipay Technical Support to configure your integration project.
• Test in the sandbox environment.

For details, see Alipay integration guide.

Scenarios

The card payment follows the auth-capture mode, which means the card payment is completed in two steps: authorization and capture. When a user pays with a card, you must request the card payment to be authorized to freeze a certain amount of funds and then request to capture the fund. After the capture succeeds, the funds are transferred to your account. You must request to capture the funds seven days after the authorization succeeds, otherwise the authorized funds are unfrozen automatically.

The card payment method is used in the following three scenarios:

Payment

You must complete the following integration steps before you can receive a card payment:

1. Obtain and display available payment methods.
2. Request to authorize the payment.
3. Obtain the authorization result.
4. Request to capture the payment.
5. Obtain the capture result.

The user experience for card payment on a shopping website is shown in the following figure:

Figure 2. User experience of card payments

1. After a user confirms the order information, the user clicks or taps Place Order to go to the payment method page.
2. On the payment method page, the user chooses a card payment method, enters information about payment elements, and clicks or taps Pay Now to continue the payment process.
3. A redirection is performed according to the payment result:

• SUCCESS: The user is redirected to the payment result page to be informed of a successful payment.
• FAIL: The user is redirected to the payment result page to be informed of a failed payment.
• PAYMENT_IN_PROCESS: The user is redirected to a mobile website provided by the card payment method. Then the user is required to enter information on this page to complete the payment.
  Note: You can redirect the user to the URL provided in normalUrl returned through the pay API. This URL varies by your business type and the payment verification type. For details, see User experience of a payment process.

4. After the payment is completed, the user is redirected to the payment result page.

During the integration process, you need to focus efforts on developing the payment method page. This page serves the following purposes:

• Display available payment methods: Payment methods are sorted according to payment information such as payment amount and the user's region.
• Manage payment status: This page displays a payment countdown and monitors the payment status to determine whether to redirect the user.
• Redirect the user to check out: Redirect the user to a checkout page by using a redirection URL that is obtained from Alipay.
• Receive payment callback (optional): Receive the payment callback by monitoring the invocation of the checkout page or by using a lifecycle function. Then you can redirect the user to the payment result page according to the payment status.

Step 1: Obtain and display available payment methods

We recommend that you obtain available payment methods and their information by using the consult API and properly display the payment methods on the payment method page.

1. Obtain payment methods

You can call the consult API to obtain a list of payment methods. In your request, specify the following parameters:

Table 1. Request parameters of the consult API

After you send the request, Alipay returns the following parameters to notify you of the necessary information about the payment methods:

Table 2. Response parameters of the consult API

2. Display payment methods

We recommend you display the payment methods in the following ways:

• You can display the name and the logo of each available payment method that are indicated by paymentOptions.logo.logoName and paymentOptions.logo.logoUrl in the payment method list. You can also display the card brands supported by each card payment method for users to choose from.
• To avoid displaying a long list of payment methods, we recommend you use a multi-level menu to deliver a better experience. Specifically, you can fold the payment methods in a menu of payment method types. After a payment method type is clicked or tapped, the corresponding payment methods are displayed. Meanwhile, to improve the payment success rate, you can also sort the payment methods by payment success rate, promotion events, and user preference.

Figure 2. Display of card payment methods

Step 2: Request to authorize the payment

When a user pays with a card, you must request to authorize the payment by using the pay API.

Necessary information about the payment needs to be collected before the payment can be authorized. The information can be collected in the following two ways that provide different authorization processes:

• Merchants (you) collect the card information
• Tokenization

During the payment authorization phase, proceed with the following steps:

1. Collect information about the payment

The information about the user's card needs to be collected for the payment. Specifically, the user needs to enter the information about the payment elements on an intermediate page and decides whether to bind the card. Card binding frees the user from entering information about the payment elements for follow-up payments. The payment information can be collected in the following two ways:

• Merchants collect the card information
• Tokenization

2. Intercept an invalid payment

To avoid a repeated payment or an expired payment, we recommend that you verify the status and validity period of the payment after the user clicks or taps Pay.

To intercept an expired payment, you can set the payment expiry time by specifying the paymentExpiryTime parameter in the payment request. If a user pays after the payment expiry time, an error is reported or the payment is refunded. Setting the payment expiry time also avoids repeated payments which might occur when the user pays long after they are redirected to the payment method page.

The time offset of a server can also lead to a repeated payment. We recommend that you determine the payment status of the order after the user pays. If the order is paid before, you can call the cancel API to cancel the payment or call the refund API to initiate a full refund to the user, and prompt the user accordingly.

3. Send a payment request

After the user clicks or taps Confirm payment, your server calls the pay API to obtain a redirection URL from Alipay and return it to your client. Perform this step according to the following instructions:

• Before the redirection URL is obtained after the request is sent, grey out the Confirm payment button in case of repeated operations triggered by the user.
• To deliver a smooth payment process, remember to pass the card information when sending a payment request.
• Set the expiry time of the request to prevent users from waiting.
• Specify parameters in the request properly according to the verification type (2D or 3D secure).

Send the request

The information that you must pass to Alipay varies by the collection mode of the card information. The following table shows the child parameters of paymentMethod that you must specify in your payment request in different collection modes:

Table 4. Description of child parameters of paymentMethod

Alipay handles the payment process based on the completeness of the information in the payment request:

• If the card information is complete, Alipay continues the payment process.
• If the card information is incomplete, Alipay provides an intermediate page to collect the card information.

Other key request parameters in the pay API are shown in the following table:

Table 5. Key request parameters in the pay API

Handle the request

The payment process might fail when you call the pay API. In this case, your server can call the pay API to reinitiate the payment request with a new paymentRequestId. However, the retried request can still fail due to network issues. We recommend that you set the expiry time of the request to prevent the user from waiting and allow the user to pay again after your server fails to obtain the redirection URL. Follow the workflow shown in the following figure:

Figure 4. Request handling logic

Receive the response

The response to a payment request varies by the following factors:

• Collection mode of the card information
• Verification type (whether 3D secure verification is used. If not, 2D secure verification is used)

The following table describes the return results of the response and provides the ways of handling the result:

Table 6. Handling of the response in different scenarios

2D secure verification:

Merchants collect the card information: If a result code of SUCCESS or FAIL is obtained, Alipay returns the payment result in the response. If a result code of PAYMENT_IN_PROCESS is obtained, Alipay returns normalUrl for further payment handling. After you receive normalUrl, you need to redirect the user to it to continue the payment process.

Tokenization: Regardless of the result code, Alipay returns normalUrl for further payment handling. After you receive normalUrl, you need to redirect the user to it or open it in a new tab to continue the payment process.

3D secure verification:

Regardless of the result code, Alipay returns normalUrl for further payment handling. After you receive normalUrl, you need to redirect the user to it or open it in a new tab for the user to complete a 3D secure verification process and continue the payment process.

4. Obtain an authorization result

You can obtain an authorization result by using one of the following three ways:

• Receive a synchronous return result.
• Receive an asynchronous notification.
• Inquire about the authorization result.

Receive a synchronous return result

In the response parameters of the pay API, if the value of resultStatus is S, the authorization is successful. If the value of resultStatus is F, the authorization is failed. If the value of resultStatus is U, you need to receive an asynchronous notification or inquire about the authorization result.

Receive an asynchronous notification

You can obtain the authorization result by receiving an asynchronous notification sent by Alipay.

You must set a notification address by specifying paymentNotifyUrl in the pay API 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 the notifyPayment notification. 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. The key parameters contained in the asynchronous notification are shown in the following table:

Table 7. Key parameters of the notifyPayment notification

You can configure the notification address in the following two ways:

• Specify paymentNotifyUrl in the pay API.
• Edit Notification URL in the Integration Settings tab of Alipay Developer Center.

Inquire about the authorization status

The asynchronous notification and the synchronous redirection can both fail to be received or implemented. The causes are described in the following table:

Table 8. The causes of failing to obtain the authorization result

We recommend that you inquire about the payment status by calling the inquiryPayment API. You can use the API 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 times out: When the payment reaches the expiry time, you can call the inquiryPayment API to check the payment status.

In the response returned through the inquiryPayment API, paymentStatus indicates the payment status. See the following table for details:

Table 9. Details of paymentStatus

We recommend that you maintain the payment status in your server and your client proceeds with the payment process based on the information provided by your server. For details about the payment status, see Payment status description.

When the card information is collected by Alipay, if a user agrees to bind a card, the card information of the user is provided in the response. The card information includes the following:

• Desensitized card number (cardNo)
• Card brand (cardBrand)
• Card token (cardToken)
• If a 3D secure verification is used, an Electronic Commerce Indicator (ECI) is returned.
• Card issuing country (issuingCountry)
• Card type (funding)
• The region where a payment method is located (paymentMethodRegion)

5. Handle a follow-up payment with a saved card

When a user agrees to bind a card for the first-time payment, the user does not need to enter the stored card information for follow-up payments.

Handle the payment

You must handle a follow-up payment according to the collection mode of the card information. This is because the collection mode determines the information you must maintain and the APIs you must call.

Figure 5. Payment processing logic according to the collection mode of the card information

Manage a saved card

A user with a saved card can update the information of the card or delete the card. To this end, see the following instructions to help users manage their cards according to the collection mode of the card information:

6. (Optional) Cancel an authorization

You can cancel an authorization by calling the cancel API. You need to cancel an authorization in the following scenarios:

• When the user initiates a refund while the payment is authorized but not captured, you need to cancel the authorization of the payment.
• When the risk control system detects a risk in a payment, you need to cancel the authorization of the payment.

If an authorization is canceled, the value of result.resultStatus in the response parameters of the cancel API is S.

Step 3: Request to capture the payment

You must request to capture the payment by calling the capture API within seven days after the authorization succeeds, otherwise Alipay automatically unfreezes the authorized funds. Some card payment methods support multiple captures of an authorized fund. The total capture amount must be no greater than the total authorized amount.

The key request parameters in the capture API is shown in the following table:

Table 10. Description of key parameters in the capture API

Step 4: Obtain a capture result

You can obtain a capture result by using one of the following three ways:

• Receive a synchronous return result.
• Receive an asynchronous notification.
• Inquire about the capture result.

Receive a synchronous return result

In the response parameters of the capture API, if the value of resultStatus is S, the capture is successful. If the value of resultStatus is F, the capture is failed. If the value of resultStatus is U, you need to receive an asynchronous notification or inquire about the capture result.

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 capture status is achieved (that is, when the capture is successful or failed), Alipay sends you the asynchronous notification through the notifyCapture notification. 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. The key parameters contained in the asynchronous notification are shown in the following table:

Table 7. Key parameters of the notifyCapture notification

You can configure the notification address in the following two ways:

• Specify paymentNotifyUrl in the pay API.
• Edit Notification URL in the Integration Settings tab of Alipay Developer Center.

Inquire about the authorization status

The asynchronous notification and the synchronous redirection can both fail to be received or implemented. We recommend that you inquire about the capture status by calling the inquiryPayment API. In the response returned through the inquiryPayment API, transactions indicates the capture status. See the following table for details:

Table 12. Child parameters of transactions

The value of transactions varies by the capture status. See the following code samples for details:

{ "transactions": [ { "transactionType": "CAPTURE", "transactionStatus": "SUCCESS", "transactionRequestId": "test_test_test_XXXX", "transactionAmount": { "currency": "BRL", "value": "110" }, "transactionTime": "2022-09-29T07:13:50-07:00", "transactionId": "2022XXXXXXXX", "transactionResult": { "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "success" } } ] }

{ "transactions": [ { "transactionType": "CAPTURE", "transactionStatus": "FAIL", "transactionRequestId": "test_test_test_XXXX", "transactionAmount": { "currency": "BRL", "value": "110" }, "transactionTime": "2022-09-29T07:13:50-07:00", "transactionId": "2022XXXXXXXX", "transactionResult": { "resultStatus": "F", "resultCode": "PROCESS_FAIL", "resultMessage": "General business failure. No retry." } } ] }

{ "transactions": [ { "transactionType": "CAPTURE", "transactionStatus": "PROCESSING", "transactionRequestId": "test_test_test_XXXX", "transactionAmount": { "currency": "BRL", "value": "110" }, "transactionTime": "2022-09-29T07:13:50-07:00", "transactionId": "2022XXXXXXXX", "transactionResult": { "resultStatus": "U", "resultCode": "PAYMENT_IN_PROCESS", "resultMessage": "payment in process" } } ] }

Chargeback

For card payments, when a chargeback occurs, Alipay provides you with the following services:

• Alipay notifies you of necessary information and freezes the funds related to the chargeback.
• Alipay provides a card association with dispute materials.
• Alipay notifies you of the liability judgment of the chargeback.

You can obtain the information about a chargeback by email or by receiving a notification sent by Alipay through the notifyDispute notification.

Receive a notification by email

After you receive a notification of the chargeback information by email, you need to respond to whether you accept the chargeback within a specific period. If you do not respond to the notification within the period, the chargeback is accepted by default. For the response periods required by payment methods, see the following table for details:

Table 13. Response periods required by payment methods

(Optional) Receive a notification through the API

You can receive a notification of the chargeback information by integrating the notifyDispute notification. Before you can receive the notification, you must configure a notification address in Alipay Developer Center.

Configure a notification address

You must edit Notification URL in the Integration Settings tab of Alipay Developer Center before you can receive the notification.

When a chargeback occurs or when the liability of the chargeback is judged, Alipay sends you the asynchronous notification through the notifyPayment notification. 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.

• When a chargeback occurs, you receive a notification of the chargeback information. The value of disputeNotificationType in the notification is DISPUTE_CREATED.
• If you have a query about the chargeback, you can put in a demurrer. When the liability of the chargeback is judged, you receive a notification of the judgment information. The value of disputeNotificationType in the notification is DISPUTE_JUDGED. The liability judgment is indicated by the value of disputeJudgedResult:

• ACCEPT_BY_CUSTOMER: The user assumes the liability. You can request to capture the payment.
• ACCEPT_BY_MERCHANT: You assume the liability. You need to refund the user the payment amount.

Refund

When a user requests a refund, you need to confirm whether the refund can be issued. If the refund is allowed, you can issue the refund by calling the refund API. For the refund periods required by payment methods, see Refund.

For a payment where a chargeback occurs and the liability is not judged, a refund is not allowed.