Complete Guide: Integrating WeChat Virtual Payment for Individual Developers

Eligibility Requirements

Before applying, verify that your mini-program meets three mandatory conditions:

Entity : Individual entity with a mainland China resident ID card.

Category : The mini-program's service category must include "Tools" (工具) . This is a hard threshold; if your mini-program is not categorized as Tools, you cannot enable virtual payment.

Prerequisites : The mini-program must have completed both certification (认证) and filing (备案).

Note: The monthly collection limit is 100,000 RMB , sufficient for validation; you can upgrade the entity later.

Application Process (5 Minutes)

Step 1: Locate the entry – Log in to the WeChat Public Platform (mp.weixin.qq.com), navigate to "Payments & Transactions" (支付与交易) → "Virtual Payment" (虚拟支付) .

Step 2: Click "Enable" – Agree to the agreement.

Step 3: Fill in details – Provide personal identity information, withdrawal account, and payment administrator info.

Step 4: Wait for review – Official documentation states results typically arrive within 5 minutes , much faster than a standard merchant account.

Step 5: Scan to sign – After approval, refresh the page and complete the electronic signature via QR code.

The entire process is self-service, requiring no manual liaison or complex merchant onboarding; it feels like enabling a regular feature.

Four Critical Configuration Values

After activation, go to the Virtual Payment backend's "Basic Configuration" and record the following (used in code): AppID – Mini-program's identity identifier (already known, no extra recording needed) OfferID – Payment merchant number (core parameter for payment requests) Production AppKey – Production environment payment secret (used to compute payment signatures) Sandbox AppKey – Test environment secret (for development and debugging)

Security warning : AppKey is the secret for signing payments. It must only reside on the backend ; never hard‑code it in frontend code or commit it to Git repositories.

Creating Virtual Goods (Props)

In the backend's "Prop Management" (道具管理) , create each sellable item:

Product name – e.g., "Monthly Membership" or "100 AI Generations".

Product ID (productId) – Your custom identifier, referenced in code.

Price – Unit is cents (分) , not yuan.

Remember to publish the product; unpublished products cannot be called from the frontend.

Integration Development: Three Steps

Overall Flow

User clicks purchase → Your backend generates order → Frontend invokes payment →
Payment succeeds → Platform pushes notification to your backend → You deliver goods to user

Step 1: Backend – Generate Order

When the user clicks "Buy", your backend must:

Generate a unique outTradeNo (your custom order number).

Save the order to the database with status "Pending Payment".

Call the WeChat API to obtain payData and return it to the frontend.

Step 2: Frontend – Invoke Payment

The frontend receives payData and calls the WeChat payment API:

wx.requestVirtualPayment({
  // Fill in payData returned by backend
  success: function(res) {
    // Payment success callback — but note: this CANNOT be used as delivery proof!
  }
})

Critical pitfall : The frontend success callback only indicates the user completed the payment action; it does not guarantee delivery. Actual fulfillment must rely on the backend notification.

Step 3: Backend – Receive Delivery Notification & Fulfill

After payment succeeds, WeChat pushes a delivery notification ( xpay_goods_deliver_notify) to your backend. Your server must:

Verify signature – Confirm the notification genuinely comes from WeChat.

Idempotency handling – The same order may receive multiple notifications; ensure goods are delivered only once.

Deliver goods – Unlock features, increment usage counts, activate membership, etc.

Return success – Respond with <xml><ErrCode>0</ErrCode></xml>.

Fallback mechanism : If the push is lost (network issues), periodically call query_order to check order status; if paid, trigger 补发货 (supplementary delivery).

iOS Payment Considerations

iOS users purchase virtual goods via Apple's In‑App Purchase (IAP) channel. Additional configuration required:

In the Virtual Payment backend's "Basic Configuration" , set the mini-program's short name (display name for Apple Pay).

Enable the "Apple IAP Payment" switch .

iOS fee rates and settlement cycles differ from Android; factor this into pricing.

Pre‑Deployment Checklist

Backend can generate unique outTradeNo.

Backend returns correct payData (including signature).

Frontend successfully invokes wx.requestVirtualPayment.

Backend receives and processes delivery notifications.

Backend implements idempotency (prevents duplicate delivery).

Scheduled query_order fallback logic exists. AppKey stored only in backend environment variables.

iOS switch configured and enabled.

Two Common Pitfalls

Pitfall 1: Using the Wrong Payment API

Virtual goods must use wx.requestVirtualPayment; using the standard wx.requestPayment will trigger risk‑control interception.

Pitfall 2: Relying on Frontend Callback for Fulfillment

The frontend success callback cannot serve as delivery proof . Always base fulfillment on the backend notification; otherwise, network failures may cause delivery without payment confirmation.

The end‑to‑end integration can be completed in half a day once familiar. The hardest part is no longer technical — deciding what to sell and at what price is where you should focus your effort .

This article is compiled from the official WeChat Virtual Payment: Individual Documentation; always refer to the latest rules.