Best practices

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

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

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

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.

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 (Checkout Payment) 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 (Checkout Payment) 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

APO offers seamless integration with a variety of payment methods. However, in certain scenarios, processing delays in the pay API may result in slow responses, preventing buyers from being redirected to the payment continuation link. This can reduce the payment success rate and negatively impact the user experience. To address this, it is recommended to set the API timeout to 10 seconds to improve response success rates. If a pay API call times out, it is suggested to reinitiate the original request to retrieve the payment continuation link.