Card payments
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:
- 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 (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).
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
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.