Mastering Payment Code Integration: Flow, Revocation, and Reconciliation

Preface

Due to business needs, a payment‑code feature is required to aggregate the payment‑code functions of major wallet apps such as WeChat Pay and Alipay.

Payment‑code payment is also known as payment‑code payment (formerly called card‑payment) for WeChat and face‑to‑face‑bar‑payment for Alipay, and sometimes referred to as QR‑code‑scanned payment . This article uses the WeChat definition and calls it payment‑code payment.

Although the term may sound unfamiliar, most users encounter it daily when a cashier asks to show a WeChat or Alipay payment code and scans it.

Example user‑side flow for Alipay is shown in the image below.

The backend call flow for payment‑code payment is illustrated next.

Detailed Payment‑Code Process

WeChat and Alipay share a similar synchronous interface: the API returns the deduction result directly without needing an asynchronous notification.

The interface is synchronous, but security and risk control may require the user to enter a password, causing the API to return a “waiting for user payment” status.

When the response contains the following codes, it indicates the user is entering a password:

WeChat: err_code=USERPAYING or err_code=SYSTEMERROR

Alipay: code=10003 or code=20000

WeChat requires password confirmation in certain situations (see image).

Alipay requires a password when the payment amount exceeds 2000 (based on testing).

Unlike other payment interfaces, payment‑code APIs do not send a message notification after a successful payment; therefore, merchants must poll the WeChat/Alipay query interface to obtain the result when the API returns a waiting status.

Revocation

If, within about 30 seconds , repeated polling still returns a waiting status, or the transaction fails or times out, the documentation recommends calling the revocation interface immediately.

When a user’s payment fails, revocation closes the order; if the payment succeeds, revocation refunds the amount to the user.

Revocation is effectively a combination of order closure and refund, but there are important differences:

Payment type limitation : revocation can only cancel payment‑code orders, while refunds support many payment types.

Refund amount : revocation only supports full refunds; the refund API can process partial amounts.

Time limitation : WeChat allows revocation within 7 days ; Alipay only on the same day. Refunds have longer windows (up to one year for WeChat, three months for Alipay).

Consequently, normal payments should use the refund API; revocation is reserved for exceptional cases.

Some systems refer to this interface as a “correction interface,” such as in industrial QR‑code payments.

Revocation‑Related Issues

Testing shows the revocation interfaces of WeChat and Alipay are idempotent; repeated revocation returns consistent results, but the response must be interpreted correctly (e.g., checking the recall field for WeChat).

Order Status

WeChat and Alipay handle order statuses differently. WeChat’s status machine is complex; after a successful revocation, a query returns REVOKED . WeChat does not allow closing payment‑code orders, so the CLOSED status never appears.

Alipay’s status after revocation becomes TRADE_CLOSED .

Reconciliation Files

After daily transactions, the next day the merchant must download WeChat/Alipay reconciliation files and verify each record to avoid missing or duplicate entries.

Reconciliation files only contain successful transactions; orders that were revoked before payment do not appear. However, if a payment succeeded and was later revoked, the file contains two records: the original transaction and a reverse‑refund record.

For WeChat, the reverse‑refund record’s transaction status is REVOKED , allowing identification via merchant order number plus status.

Alipay’s revocation‑generated refund records look identical to normal refunds; however, the refund batch number matches the original internal order number for revocation, while normal refunds use a merchant‑provided batch number, enabling differentiation.

Revocation Failure

In rare extreme cases where multiple revocation attempts fail, manual intervention is recommended rather than automated handling.

Many times, manual assurance is more efficient and lower‑cost than trying to devise an automatic solution for rare edge cases.