Payment
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.
Integration steps
Complete the following integration steps for a card payment:
- Obtain and display available payment methods.
- Request to authorize the payment and display the payment result.
- (Optional) Cancel the authorization payment.
- 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 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.
Request parameter | Required/optional | Description |
merchantRegion | OPTIONAL | The region where you receive card payments. The value of this parameter is a two-letter ISO code. Specify this parameter if you would like to receive card payments in Singapore or Hong Kong. The allowed values are as follows:
|
paymentAmount | REQUIRED | The transaction currency and amount. |
env | REQUIRED | The type of the client that is used for the payment, such as a desktop browser, a mobile browser, or a mobile application. |
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:
Response parameter | Description |
paymentOptions.paymentMethodType | For card payment methods, the value of this parameter is fixed to |
paymentOptions.paymentMethodRegion | For card payment methods, this parameter indicates the card issuing country. The value of this parameter is a two-letter ISO code or
|
paymentOptions.enabled | Indicates whether the payment method is available. |
paymentOptions.paymentOptionDetail.supportCardBrands.logo | The card brand logo of the card payment method. For details about the possible values, see Card brands. |
paymentOptions.paymentOptionDetail.supportCardBrands.cardBrand | The card brand supported by the card payment method. For details about the possible values, see Card brands. |
paymentOptions.paymentOptionDetail.funding | The card type. The possible values are as follows:
|
Table 2. Response parameters of the consult API
Display payment methods
We recommend you display the payment methods in the following ways:
Display method of payment methods | User experience |
For the user's first payment, you can display the card logo (paymentOptions.logo) and the corresponding card brand (paymentOptions.paymentOptionDetail.supportCardBrands.logo) together. |
|
For users who pay with saved cards, you can display the card logo (paymentOptions.logo), the corresponding card brand (paymentOptions.paymentOptionDetail.supportCardBrands.logo), and the masked card number together. |
|
Figure 3. Display methods and user experiences of payment methods
Step 2: Request to authorize a payment
You can integrate through SDK or API to initiate authorization for a card payment.
SDK | API |
This is for merchants who do not have high requirements for customization in the payment process and prefer lightweight integration. By reducing page redirects in the payment process, it provides users with a better payment experience, thereby increasing the success rate of payments. | This is for merchants who have high requirements for customization in the payment process. |
Figure 4. Descriptions of SDK and API integrations of card authorization
- About how to use SDK to integrate, see SDK integration.
- About how to use API to integrate, see API integration.
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 must request to capture a card payment by calling the capture API (POST/v1/payments/capture) within seven days after the authorization succeeds, otherwise Alipay automatically unfreezes the authorized funds of the payment. The total capture amount must not exceed the total authorized amount.