Best practices
This topic introduces multiple best practice solutions to help you enhance product experience and payment efficiency:
Client-side optimization
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 on the APM payment page but faces issues being redirected to the URL you set in subscriptionRedirectUrl-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 subscriptionRedirectUrl 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:
- Subscription successful: After the subscription is activated, the page will display content related to the subscription.
- Subscription failed: If the subscription fails, provide guidance for buyers to complete retrying the payment method binding.
- Subscription failed, payment failed: This indicates that the payment method binding was successful but the payment failed. It is recommended that the buyer checks their payment capabilities in the respective APM, such as ensuring sufficient balance, and guide them to create the subscription again.
- Subscription processing: If no subscription result notification is received, show a loading effect and pause for 3-5 seconds, then query the server again for the latest subscription result. If the result is still uncertain (neither successful nor failed), it is recommended to display "Binding in process" or "Check final results in the order management portal." 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.
API timeout settings
Antom supports direct integration of multiple payment methods. In certain cases, the create 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 create API to at least 10 seconds. If the API call times out, it is recommended to retry the original request to obtain the payment result or payment continuation URLs.