Card payments

This article introduces the integration process of card payment methods.

Prerequisites

Before you begin, you must complete the following tasks:

• Register in Antom Developer Center.
• Set your keys.

Please refer to the Integration guide for more details.

Payment flow

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

The overall process of card payment is shown in the following figure:

Figure 1. Payment authorization and capture process

Figure 2. The process of canceling authorized payments

Notes: Acquirer's routing is divided into the following two cases:

• Intelligent Routing: APO enables intelligent routing for you by default to prioritize the payment success rate, based on big data and AI algorithms to intelligently decide the optimal acquirer for each transaction to achieve a higher payment success rate. You can also choose to disable the intelligent routing capability.
• Custom Routing: You can customize the routing rules in APO. The transactions that meet the rules will be routed to the target acquirer according to the rules. Custom routing has a higher priority than intelligent routing. If you do not turn off intelligent routing, transactions that do not meet the custom routing rules will be routed by intelligent routing to help you decide the best acquirer.

For more information on how to customize your routing rules, you can contact Antom technical support.

Integration Steps

Complete the following integration steps for a card payment:

1. (Optional) Independent card binding.
2. Display available payment methods.
3. Request to authorize the payment.
4. (Optional) Cancel the authorization payment.
5. Request to capture the payment.

Step 1: (Optional) Independent card binding

You can access the ability to bind a bank card independently through APO, and your buyers can choose to add a bank card to your platform anytime, anywhere, including binding a card before paying for a purchase or adding a bank card after choosing a card-based payment method during a purchase, to facilitate quick payment for subsequent purchases. Once the card is bound, APO will return the corresponding cardToken to you, and the subsequent payment can be completed by passing in the cardToken, without the need for the buyer to re-enter the card information. If you don't choose to use the independent card-binding capability, you can also provide the buyer with the card-binding capability during the payment authorization process.

Please refer to Independent card binding for more details.

Step 2: Display available payment methods

Contact your technical support for available payment methods. We recommend you display the payment methods in the following ways:

Table 1. Display methods and user experiences of payment methods

Step 3: Request to authorize a payment

The process of initiating authorized payments can be integrated through two methods: API or SDK:

Table 2. Description of different integration methods for authorized payments

If you don't choose to use the independent card-binding capability, you can also provide the buyer with the card-binding capability during the payment authorization process.

• Please refer to SDK integration for details on how to use SDK for integration.
• Please refer to API integration for details on how to use API for integration.

Step 4: (Optional) Cancel the authorization payment

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.

Please refer to Cancel for more details.

Step 5: Request to capture the payment

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

• Automatic capture: APO automatically captures funds immediately after the user authorizes the payment. The automatic capture is activated when one of the following conditions is met:

• You set the value of paymentFactor.captureMode in the pay or createPaymentSession API to AUTOMATIC.
• You leave the value of paymentFactor.captureMode in the pay or createPaymentSession 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 APO 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 or createPaymentSession API to MANUAL.

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

Please refer to Capture for more details.