This article introduces how to integrate card payments using APIs. This integration method is suitable for merchants who have high requirements for customization in the payment process.

Prerequisites

Before you begin, you must complete the following tasks:

• Register in Antom Dashboard.
• Set your keys in Antom Dashboard.
• Configure an address for receiving asynchronous notifications.

For details, see Integration guide.

Workflow

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. By default, Alipay+ automatically handles funds capture for you. You can also choose to capture funds manually by calling the capture API.

The overall workflow of a card payment is shown in the following figures:

Figure 1. Authorization and capture workdflow

Figure 2. Authorization cancellation workflow

Integration steps

Complete the following integration steps for a card payment:

1. Obtain and display available payment methods.
2. Request to authorize the payment and display the payment result.
3. (Optional) Cancel the authorization payment.
4. Request to capture the payment.

Note: You can authorize a card payment by integrating API or SDK.

Step1: Obtain and display payment methods

We recommend that you obtain available payment methods and their card brand information by using the consult API and properly display the payment methods on the payment method page. You can also display the corresponding payment methods in the form of static icons.

Obtain payment methods

You can call the consult (Cashier Payment) API (POST/v1/payments/consult) to obtain a list of payment methods.

In your request, you need to specify the payment amount of the transaction, the terminal type of the device where the user places the order, and the region information. The response returns the names and logos of available payment methods, and whether the payment methods are able to use. For the specific use of the consult API, see consult (Cashier Payment).

Table 1. Request parameters of the consult API

After you send the request, Alipay+ returns the available payment method information. Some key parameters are shown as follows:

Table 2. Response parameters of the consult API

Display payment methods

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

Figure 3. Display methods and user experiences of payment methods

Step 2: Request to authorize a payment

After a user confirms a card payment, you need to request an authorization payment by calling the pay API. For more information about how to complete an authorization payment, see Authorization payment.

Step 3: (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 successfully, the value of result.resultStatus in the response parameters of the cancel API is S.

Step 4: Request to capture a payment

You can choose one of the following methods to capture funds：

• Automatic capture: Alipay+ automatically captures funds immediately after the user authorizes the payment. The capture result is then communicated to you via an asynchronous notification. The automatic capture is activated when one of the following conditions is met:

• You set the value of paymentFactor.captureMode in the pay API to AUTOMATIC.
• You leave the value of paymentFactor.captureMode in the pay API empty or you do not pass in this parameter.

• Manual capture: You must initiate fund capture by calling the capture API within seven days after successful authorization, otherwise Alipay+ automatically unfreezes the authorized funds of the payment. The total capture amount must be equal to the total authorized amount. You must set the value of paymentFactor.captureMode in the pay API to MANUAL.

Note: For card payments, it is recommended to confirm the successful capture result before shipping.

For more information about fund capture, see Capture.