Best practices

2026-01-27 01:58

This document presents actionable strategies to improve user experience and payment performance, driving your business growth.

Intelligent risk control service
Security expansion package
Order query after redirecting to the merchant result page
Merchant-initiated transaction cancellation
Payment failure retry

Intelligent risk control service

EasySafePay's built-in intelligent risk control capabilities requires precise risk control field inputs during payment session creation (annotated for risk control purposes). The accuracy and completeness of these data points directly determine the system's fraud detection effectiveness.

The following parameters are essential for effective risk control. Please transmit them accurately. For detailed field specifications, refer to createPaymentSession (EasySafePay).

Parameter type	Parameter name	Description
Equipment & Environment fields	env.clientIp	The client device's IP address.
Order Fields	order.goods: referenceGoodsId goodsName goodsCategory goodsUnitAmount goodsQuantitygoodsUrl deliveryMethodType	Product details including product ID, name, category, unit price, quantity, URL, and delivery method.
	order.shipping: shippingName shippingAddress shippingPhoneNo shipToEmail shippingCarrier	Shipping information including recipient details and logistics carrier name. For digital goods, provide shipToEmail for the recipient email address.
	order.buyer: referenceBuyerId buyerPhoneNo buyerEmail buyerRegistrationTime	Buyer information including buyer ID, phone number, email address, and registration time. At least one of the following must be provided: ID, phone number, or email address.

Security expansion package

When integrating the SDK resource package, please follow the specifications to add the security extension package. For iOS, refer to SDK security package; for Android, refer to Integrate the security package.

This component collects terminal device information for risk identification, enhancing payment security and service reliability.

Order query after redirecting to the merchant result page

Call the inquiryPayment API and dynamically display content on the results page according to different payment states.

Payment success: Display shipping-related information.
Payment failure: Display payment retry instructions.
Payment in process:

Display loading status for 3-5 seconds, then automatically initiate a secondary query.
When the system continuously returns a processing status, display “Your order is being processed. Please check the results later in the Order Management Portal.”

Notes:
Avoid non-deterministic descriptions like "network latency".
All status prompts must strictly match the API response.

Merchant-initiated transaction cancellation

If the merchant's order timeout closure occurs earlier than Antom's payment order timeout, a "payment successful" notification may still be received after order closure. In such cases, invoke the cancel API to initiate a buyer refund.

Payment failure retry

When an order payment fails and retries are permitted for the same order, follow this workflow:

Set referenceOrderId as the order ID and paymentRequestId as the payment order ID in the payment request.
Before retrying payment, check the order status:

If already successful, display "Payment completed".
If still processing or failed, call the createPaymentSession (EasySafePay) API again to obtain new paymentSessionData.

Ensure each order is only associated with one successful payment. If duplicate successful payments are detected, call the cancel API to initiate a refund.