Guide to Design of System Order Query Capability

1. Background

Weixin Pay provides the order query API to enable cooperative merchants/institutions to confirm order status. In case of network jitter or exception of the callback notification service, the merchant/institution needs to call the order query API to obtain the order status.

2. Influence

• Reputation of merchants/institutions: If a merchant/institution cannot query order status in the system, the payment result notification (payment callback) will become the only channel for the merchant/institution to obtain the order status in real time. If a service exception occurs to the callback notification address, the status of any order cannot be synchronized in the system during the exception. Consequently, a large number of merchants cannot use Weixin Pay, and users lodge complaints, which seriously affect the reputation of institutions, merchants, and Weixin Pay eventually.

• Unilateral account complaint: If the system of a merchant/institution fails to synchronize the order status due to a network jitter or short-term callback exception, and the merchant/institution does not implement the order query logic in the system, The amount may be deducted from the user's account, but the system of the merchant/institution insists that the order has not been paid and goods cannot be delivered to the user, which eventually results in a unilateral account complaint.

3. Objective

All the impacts will lead to users' doubt and negative impression of the service quality of the institution/merchant and the stability of Weixin Pay service. Therefore, the function logic of order query needs to be realized for all the institutions/merchants in the acquiring system. Even if the callback notification cannot be received, the order status can be obtained in time, thus ensuring the stability of system services.

4. Suggestion on Implementation of Order Query Logic

We provide two order query solutions for reference by institutions during system optimization:

Solution 1

Normally, when a payment is completed, Weixin Pay sends a payment success notification to the callback notification address of the merchant/institution. After receiving the payment success notification, the merchant/institution needs to return the specified content and update the order status in the order database, as shown below:

However, in case of system or network jitter or when the merchant’s callback address is unavailable, the merchant/institution needs to actively call the order query API to obtain the order status.

The institution/merchant can trigger order query once at the end of the order business validity period (when the order expires), ensuring that the status recorded is correct when the order expires. This ensures that the order that has not been successfully paid will be closed and refunding can be initiated for the order that has been successfully paid. Therefore, the problem of unilateral account is avoided. The following figure shows the detailed logic:

However, there is still a certain delay in the order query timeliness of this solution, which may cause the user to wait long and lodge a complaint. Therefore, if conditions permit, it is recommended to optimize the system by referring to solution 2.

Solution 2

The logic of waiting for callback is the same as that of solution 1, but for the design of order query logic, it is recommended that the institutions/merchants establish two order query links, one is triggered by front-end callback, and the other is triggered to enter the task queue when an order is placed.

When an order is placed with the merchant, the order data is written into the merchant’s order database, the order is added to the order query queue synchronously, and the order query API of Weixin Pay is called at a fixed frequency to query the order status, as shown below.

For the scenarios involving the front-end page or application callback (including app payment, mini program payment, H5 payment, and JSAPI payment), when a user completes payment, the system will return to the app/mini program/Web page of the merchant/institution, and front-end callback will also take place. The merchant/institution can judge whether the user has cancelled the payment according to the front-end callback result. If the return result of front-end callback is “fail”, it is confirmed that the user has cancelled the payment. Then, the order can be directly removed from the order query queue and will no longer be queried. If the return result of front-end callback is “success”, it can be confirmed that the payment is completed, but the payment result depends on the back-end callback or order query result.

If the payment is confirmed completed, the order query service within the merchant/institution will be triggered once and the order query module of the merchant/institution will query the current status of the order in the background database. If the merchant/institution has received the callback notification at that time, the order query result is “success”, the query service module can synchronize the order status to the front end, and the payment success message is displayed on the business page of the merchant/institution. If the merchant/institution does not receive the callback notification, or the notification cannot be received due to other reasons, the order status is determined by the order query queue result, as shown below.

5. Order Closed Loop Processing

When the transaction status obtained in the last order query is not “SUCCESS”, it is recommended that the institutions or merchants call the order closing interface immediately without time difference.

6. Post-check to Prevent Omission and Error

After 10 a.m. on day T + 1, the merchant calls the reconciliation file downloading API of Weixin Pay or logs in to the merchant platform of Weixin Pay Downloading Reconciliation API to manually download the transaction statement on day T, and checks the orders in the merchant system one by one against the order data in the reconciliation file.

The following circumstances may occur during the check:

1) The orders can be matched and the statuses of all orders are payment success. This is a normal circumstance. The reconciliation succeeds.

2) The orders can be matched, but some orders at the merchant sides are not paid successfully. In this case, the merchant needs to decide whether to update the order status to payment success and deliver the goods to the user or initiate a refund to the user according to the actual situation.

3) Order matching fails, and no record is found in the merchant system for the order number in the reconciliation file. This is an abnormal circumstance. The merchant needs to check whether data is abnormal in the system.

4) Order cannot be matched, and no record is found in the reconciliation file for a successful order in the merchant system. This is an abnormal circumstance. The merchant needs to check whether the order processing logic has a bug.