This topic introduces multiple best practice solutions to help you enhance product experience and payment efficiency:

• Client-side optimization
• Payment result display
• Payment failure retry
• API timeout settings
• Intermediate page optimization

Client-side optimization App only

It mainly involves optimization of the following items:

• Handling of a disambiguation box on Android.
• Determine whether the buyer has installed the payment method app.
• Completing payments on the merchant app.

Refer to Payment continuation URL for more information on app terminals.

Payment result display

When redirecting to the merchant result page, you may encounter one of the following scenarios. Refer to the following recommended solutions:

Redirection handling

If the buyer successfully completes the payment but faces issues being redirected to the URL you set in paymentRedirectUrl-whether due to network issues or payment method limitations-consider the following points:

• Do not use the client redirection as the basis for determining the success of the payment.
• If paymentRedirectUrl of the payment method page fails to redirect to the merchant page, the buyer may manually click to return to the original merchant page. To prevent buyers from mistakenly attempting to pay for the order again, it is recommended to implement a pop-up window on the original merchant page. This pop-up should allow for transaction result inquiries. When buyers click the pop-up window, it should display the transaction result, thereby preventing any duplicate payment attempts.

Trigger order result query after redirection

If the merchant side displays a result pop-up window after calling the inquiryPayment API, handle the result accordingly:

• Successful payment: The page will display the content related to the shipment after successful payment.
• Payment failure: State that the payment has failed and offer guidance for a payment retry to encourage order completion.
• Payment processing: Display a loading effect and pause for 3-5 seconds, then query the server again for the payment result. If the result remains inconclusive (neither success nor failure), it is recommended to display "Order processing" or "Check final result in Order Management Center". Avoid attributing delays to network processing.

Display merchant result page for card payments

Card payments follow an authorized-capture model. The successful capture result should be the sole basis for shipping goods and displaying final payment results. For different capture modes, consider the following display recommendations:

• Automatic capture: Antom automatically initiates capture after successful authorization. However, there is a delay between authorization completion and the sending of the asynchronous capture notification—typically around 2 seconds. Based on the P95 latency, it is recommended to wait at least 4 seconds after authorization before displaying the final payment result to the buyer.
• Manual capture: Since successful authorization does not equate to final payment success (capture must be initiated manually), do not display final statuses such as "payment successful" or "awaiting shipment" immediately after authorization. Wait until capture is successful before showing the final status.

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 (One-time Payments) 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, call the pay (One-time Payments) API again to obtain a new normalUrl for redirection. Though referenceOrderId remains the same since it's the same order, you must update paymentRequestId for the subsequent payment attempt

3. Ensure only one successful payment is associated with each order. If multiple successful payments are detected for a single order, call the cancel API to initiate a refund for the buyer.
4. For payment methods that do not offer refunds, it is recommended to cancel the initial payment before initiating a new one.

The integration process varies depending on whether the payment method supports refunds.

API timeout settings

Antom supports direct integration of multiple payment methods. In certain cases, the pay (One-time Payments) API may experience processing delays, which can lead to untimely responses. This may affect the redirection of buyers to payment continuation URLs, thereby reducing payment success rates and impacting user experience.

To mitigate this, it is recommended to set the timeout for the pay (One-time Payments) API to at least 10 seconds. This allows sufficient time to synchronously obtain payment results or redirection URLs required for 3DS authentication. If the API call times out, it is recommended to retry the original request to obtain the payment result or payment continuation URLs.

Intermediate page optimization

To achieve unified access to multiple payment methods, Antom simplifies the integration process by providing intermediate pages for processing specific payment elements for some payment methods. However, this intermediate page redirection may increase the burden on the user experience and affect payment success rate. In order to improve the user experience, reduce page redirections, and improve the payment success rate, we recommend that you customize and optimize some payment methods according to the following solutions:

• Bank pre-front solution
• Payment element pre-front solution
• QR code/password pre-front solution