Antom, leading provider of tailored payment solutionsAntom, leading provider of tailored payment solutions

Best practices

This article introduces multiple best practices to help you enhance product experience and payment efficiency:

  • Payment result display
  • Order closure on merchant side
  • Payment failure retry
  • API timeout settings

Payment result display

After calling the pay (Auto Debit) API, handle the result according to the guidance provided:

  • Payment is successful: Display shipping-related content on the payment result page.
  • Payment failed: Notify the buyer of payment failure, and guide the buyer to retry payment to complete the order.
  • Payment is being processed: Display a loading effect and pause for 3-5 seconds, then query the server again for the payment result. If the result remains unknown (neither success nor failure), display "Order processing" or "Check final result in Order Management Center". Avoid attributing delays to network processing. Antom will notify the final payment result within 1 minute.

Order closure on merchant side

If the order on the merchant side has set the API timeout (that is, the payment is not completed within the specified time) and the Antom payment receipt has not progressed to the successful or failed state, you also need to call the cancel API to cancel the payment when closing the order to ensure that the status of the receipt is the same on both sides.

Payment failure retry

If a payment attempt fails and the buyer can retry payment for the same order, follow the steps below to provide a seamless experience for the buyer:

  1. In the pay (Auto Debit) request, set referenceOrderId to the order ID and paymentRequestId to the payment order ID.
  2. Before retrying payment for the same order, check the order status:
    • If payment is successful, display "Payment completed" to the buyer.
    • If payment fails, cancel the failed payment by calling the cancel API, and initiate a new payment by calling the pay (Auto Debit) API with a new paymentRequestId.
  1. Ensure only one successful payment is associated with each merchant order. If multiple successful payments are detected for a single order, call the cancel API to initiate a refund for the buyer.

API timeout settings

In some cases, delays in processing order of payment method APIs may prevent timely responses. If you have set API timeout, it is recommended to set it to 10 seconds. If the payment API call times out, it is recommended to wait for the asynchronous notification or call the inquiryPayment API to obtain the payment result.