Card payments
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 funds. After the capture succeeds, the funds are transferred to your account.
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.
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.
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 request an authorization payment by calling the pay API. Authorization is divided into server-to-server mode, card information hosting mode and Hosted payment page mode. 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 need to initiate fund capture by calling the capture API (POST/v1/payments/capture) 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.
For more information about fund capture, see Capture.