Avoid Common Pitfalls When Implementing WeChat Pay v2: A Backend Guide

When integrating WeChat Pay v2 on the backend, several critical details must be handled correctly to ensure reliable and secure transactions.

1.1 Do Not Trust Front‑End Amounts

Always retrieve the product price from the database; the front‑end should only send the product ID.

1.2 Correct Trade Type Field

The v2 API requires different trade types to invoke corresponding payment methods; using the wrong trade type leads to failures.

1.3 Second Signature Required

After obtaining the pre‑pay transaction session identifier, perform a second signature. Only the second‑signed value should be returned to the front‑end.

1.4 Mini‑Program Can Bind to Other Merchants

A mini‑program may be associated with multiple merchant IDs simultaneously.

1.5 Currency Unit Is Cents

WeChat Pay amounts are expressed in fen (cents), with the minimum amount of 0.01 CNY. In contrast, Alipay uses yuan.

1.6 Prevent Duplicate Consumption

Use transactional operations to ensure an order is processed only once. After successful processing, update the order status; subsequent attempts should immediately return success without re‑executing business logic. A distributed lock keyed by the order number can also guarantee single‑threaded handling.

1.7 Verify Payment Result Signature

Always verify the asynchronous payment notification using the configured private key. The following code demonstrates the verification and subsequent order status update.

// Process internal business logic
try {
    // Verify payment result signature
    boolean valid = WXPayUtil.isSignatureValid(map1, weixinpaypartner);
    if (valid == false) {
        log.info("Signature mismatch" + outTradeNo);
        return "ERROR";
    } else {
        // 1. Update order status
        dealAfterSuccess(basOrder, time_end, transaction_id, result_code);
        log.info("Signature verified" + outTradeNo);
        result = CommUtils.setXml("SUCCESS", "OK");
        log.info("Response to WeChat" + result);
        return result;
    }
} catch (Exception e) {
    e.printStackTrace();
    return "ERROR";
}

Skipping verification may allow forged payment result pages.

1.8 Log Non‑Transactional Operations in Payment Notifications

If a template message or public account notification is sent after payment, and the transaction fails later, the notification may already have been delivered. Record whether non‑transactional actions have been performed for each order to avoid duplicate pushes during retries or compensations.

1.9 Unified Order API in v2

The v2 unified order interface supports service accounts, H5, mini‑program, and even app orders, providing a single entry point for all client types.