WeChat Mini Program Virtual Payment Integration: Lessons Learned and Common Pitfalls

Differences Between Virtual Payment and WeChat V3 Payment

Virtual payment changes the entire transaction mechanism compared with ordinary WeChat payment.

Payment initiation : ordinary payment creates a pre‑order on the server and the client launches payment with the pre‑order number; virtual payment generates only signature parameters on the server, and the actual order is created when the client invokes wx.requestVirtualPayment.

Payment result confirmation : ordinary payment relies on callback notification plus reconciliation polling; virtual payment adds a “confirm delivery” step – the developer must confirm that the virtual item has been delivered before the order is closed. If the push is lost, a polling query of the order status is used as a fallback.

Refund process : ordinary payment refunds are synchronous – a single API call returns the result. Virtual payment refunds are asynchronous; the result is delivered via a push notification. Apple‑based iOS payments cannot be refunded through the WeChat API and must be processed through the App Store.

Fee rates : ordinary payment uses a merchant account with a fee of about 0.6‑1 %; virtual payment charges a technical service fee of 10 % (12 % on iOS) plus a temporary 5 % Tencent service fee (exempted in 2026).

Practical Integration

Confirm Three Prerequisites

Qualification : apply for virtual‑payment qualification in the Mini Program PC management console. Official review time is 1‑7 business days; the author’s experience shows approval within an hour.

Item mode : virtual payment supports several modes such as direct‑item purchase and token recharge. Identify the mode that matches your product because the APIs differ significantly.

Base library version : the client‑side API wx.requestVirtualPayment requires a base library version of 2.19.2 or higher.

Feature Refactor

The existing V3 payment is retained for other platforms, so the backend must support multiple payment methods. The overall architecture is shown below:

The virtual‑payment flow remains a straight line: Initiate → Confirm → Refund .

1) Initiation

The backend adds an endpoint that validates pricing and generates the signature parameters. The client replaces the old call with wx.requestVirtualPayment to launch the payment UI. The signature is the core of this step: serialize the fixed fields (offerId, buyQuantity, env, currencyType, productId, goodsPrice, outTradeNo, attach), compute paySig / signature, and return the raw string to the client, which passes it unchanged to wx.requestVirtualPayment.

The client‑side API returns many error codes; developers should map them to user‑friendly messages (see the screenshot for a partial list).

2) Confirmation

The push notification configured in the Mini Program backend is the primary confirmation channel. The author recommends enabling secure‑mode encrypted transmission: the receiving endpoint must decrypt and verify the payload; any missing or invalid ciphertext should cause a failure response and skip business processing. This differs from V3 payment, where developers configure a direct server callback.

3) Refund

Refunds are initiated from the management console, not from the client. Because the refund is fully controllable, a lost push can be retried without additional polling logic. Adding a polling loop for refunds would increase complexity without benefit.

Execution Pitfalls

Order numbers are one‑time use

In V3 payment the author reused an unpaid order number for retries. Virtual payment forbids this – each order number can be used only once. After a cancellation or failure a new order must be created; reusing the old number returns error ‑15002.

Confirmation must not rely solely on push

WeChat push notifications are not 100 % reliable. If a push is lost, the user may have paid but the service does not activate the entitlement, causing an incident. Therefore a periodic poll of pending orders is required as a safety net. The poll and the push share the same idempotent entry point so that a single order is activated only once.

iOS orders cannot be refunded programmatically

iOS virtual‑payment orders are processed through Apple Pay. Developers cannot trigger a refund via the WeChat API; users must request a refund in the App Store. Consequently iOS orders must be handled separately from WeChat‑channel orders.

Sandbox testing is not free

The sandbox environment still performs real deductions; only the service fee is waived. For iOS, scanning the QR code with a real iPhone will actually charge the user, so adjust the price before testing.

Configuration takes about ten minutes to take effect

After changing an item’s price or other settings in the merchant console, WeChat propagates the change after roughly ten minutes. Initiating payment before this window results in errors, so wait before testing.

Final Thoughts

Virtual payment is a completely new mechanism with many constraints and a substantially higher service fee (up to 12 % on iOS). The most critical issues are the one‑time order‑ID rule, the need for push + polling confirmation, and the separate handling required for iOS refunds.