Payment retry mechanism
Antom provides a payment retry mechanism. For payment sessions created via the createPaymentSession (One-time Payments) API, buyers can make multiple payment attempts and freely switch payment methods within the validity period of the payment session, without requiring the merchant server to re-invoke the API. The following integration paths support this retry mechanism:
Payment retry scenarios
Retry type | Trigger scenario | Handling method | Server-side involved |
In-page retry | Buyer enters incorrect information, wrong password, insufficient balance, etc. | Correct the information (e.g., card number) within the page of Payment Element or CKP, then click the payment button to resubmit directly. | ❌ |
Switch payment method | The current payment method fails and the buyer wants to try another payment method. | Select a different method from the payment method list on the page of Payment Element or CKP, then click the payment button to submit directly. | ❌ |
3DS authentication failure | 3D Secure authentication fails. | The merchant's server needs to re-invoke the createPaymentSession (One-time Payments) API to create a new session. | ✔️ |
Retry after payment session expires | The payment session exceeds the validity period (default is 1 hour). | The merchant's server needs to re-invoke the createPaymentSession (One-time Payments) API to create a new session. | ✔️ |
Retry after order cancellation | The merchant has actively canceled the order, but the buyer wishes to pay again. | The merchant's server needs to re-invoke the createPaymentSession (One-time Payments) API to create a new session. | ✔️ |
FAQs
How many times can a buyer switch payment methods within Payment Element or Checkout Page?
There is no limit on the number of switches. The default validity period of a payment session is 1 hour. You can also customize the expiration time via the paymentSessionExpiryTime parameter. Buyers can switch payment methods and attempt payment an unlimited number of times within the validity period of the payment session.
Can the same payment session be reused if the order amount needs to be modified?
No. Modifying the order amount is considered an order information change and requires the following steps:
- If payment has already been initiated, you need to call the cancel API to cancel the current payment session by following the steps of Cancel.
- Call the createPaymentSession (One-time Payments) API again to create a new session.
- Use the new paymentRequestId and the updated amount to proceed with subsequent steps.
In the Checkout Page scenario, will the payment session still be retained after the buyer closes the browser?
Yes. The default validity period of a payment session is 1 hour. You can also customize the expiration time via the paymentSessionExpiryTime parameter. The payment session persists within its validity period from the moment of creation. Even if the buyer closes the browser, they can still continue the payment process by accessing the original Checkout Page link within the validity period.
If multiple successful payments occur for the same order, how does the system handle this?
The Antom system will take the last successful payment as the final status and automatically initiate refunds for all previous successful payments. The refund rules are as follows:
- Final status: The system considers the last successful payment as the final valid transaction.
- Automatic processing: All previous successful payments will be automatically refunded in full.
- Refund path: Refunds will be returned to the buyer's original payment account used at the time of payment.
Note:
- When you receive notifications of multiple successful payments, you do not need to manually call the refund API. The system will handle this automatically.
- You should update the order status based on the last payment notification.
- If a buyer inquires about why multiple charges occurred, you can provide such explanations: "The system has automatically initiated refunds, and the funds will be returned to your original payment account within 5-14 business days. Please wait patiently."
- If the refund has not been received after 14 business days, please contact Antom Technical Support and provide the paymentId sent by the notifyPayment API to check the refund status.
What results will the inquiryPayment API return within the payment session validity period?
The inquiryPayment API may return the following three results:
- Payment successful: Returns the payment success result.
- Payment failed but the payment session is still valid: Returns
PAYMENT_IN_PROGRESS, indicating that the payment is still in progress. - Payment not successful and the payment session has expired: Returns
ORDER_IS_CLOSED, indicating that the transaction has been closed.