# Virtual Payment

# I. Product Introduction

To protect user rights and enhance transaction security, virtual items provided by developers within Mini Program (including virtual currency, unlocked features, subscription content, paid services, tips, and virtual gifts) require integration with Mini Program's virtual payment system for both purchase and payment. Developers can activate a new WeChat Pay Merchant account through the Mini Program management backend’s Virtual Payment module, enabling services like bill inquiry and fund withdrawal. The platform charges a technical service fee based on the payment amount generated by this payment method.

This document outlines the core processes of virtual payment, applicable to Android, HarmonyOS, and Windows platforms. iOS requires additional activation and adaptation procedures; please refer to the relevant documentation for details.

⚠️ Please use the sandbox environment for testing. Using the live environment will incur technical service fees.

⚠️ For Android/HarmonyOS/Windows: Use version 2.19.2 or later of the base library.

⚠️ For iOS: Use WeChat client version 8.0.68 or later.

# 1.1 Activation Requirements

# 1.2 Activation Process

After completing the qualification application, click [Virtual Payment] in the left sidebar to access the activation page.

If your account meets the requirements, click [Activate] to sign the agreement and upload documents, thereby activating a new Merchant account.

# 1.3 Activation Steps

# Step 1: Read the Agreement

Read the virtual payment agreement and check the box “I have read and agree to the terms” before proceeding.

# Step 2: Submit Merchant Documents to Activate the Account

Provide business license details, withdrawal account information, and payment administrator details.

# Step 3: Check Account Status and Review Documents

After submitting the documents, wait for approval on the same page. Approval usually takes 1–7 working days, and the status can be checked upon subsequent visits.

# Step 4: Account Verification

Perform account verification (skip if the payment administrator is a corporate legal representative).

# Step 5: Scan Code to Sign Agreement

Scan the code to complete the agreement signing. After signing, the documents will be reviewed. Developers can leave the page.

⚠️ Account verification and signing may not be immediate. Developers can exit the page and resume configuration later.

Wait approximately 1–2 working days before checking the Virtual Payment module. If the status shows “Signed” or you’ve entered the Merchant management module, the signing is complete and the secondary Merchant account has been activated.

# Step 6: Access the Merchant Management Backend for Bill/Order Inquiry, Token/Item Configuration, and Fund Management

Once the previous steps are completed, the Virtual Payment section will transform into the Merchant management module. The platform provides a Merchant management backend for configuring basic information and managing tokens and items (choose item or token management as needed).

Detailed functions are as follows:

# Basic Configuration

1. Basic Info: Developers can view their basic configuration details here, including appid/offerid/appkey, shipping settings, etc.

   

2. Token Configuration: Developers can configure tokens by entering names and setting conversion rates. Tokens cannot be modified after creation, and names must comply with legal regulations.

3. Item Management: Developers can upload items for development and release versions. Items can be edited, saved, and released, with shipping configurations available (item names must comply with legal regulations).

   

# Fund Management

Supports checking account balances, withdrawals, daily bill viewing (including order numbers and developer earnings), and bill detail viewing (download functionality will be added later).

Note: The pending settlement amount refers to the amount not yet allocated (before deducting technical service fees).

Settlement cycle: T+3. Funds are frozen after a transaction and allocated 3 days later.

# Transaction Orders

It is possible to query order status (including the transaction and shipping status of token/gadget orders), and refunds can be processed (download functionality will be available later).

# Advertising Funds

The platform will establish advertising fund policies to support developers' ad campaigns. Merchant can check the advertising funds granted by the platform in the Virtual Payment -- Advertising Fund Management interface.

# II. Development Process

# 2.1 Sequence Diagrams

# Gadget Direct Purchase Flowchart

Notes

• 【7. User Payment Successful】: Triggered by the success callback of wx.requestVirtualPayment. It may be lost if, for example, WeChat exits abnormally.
• It is recommended to implement either [Shipping Push Branch] or [Shipping Polling Branch]. Using both together ensures a more reliable experience.

# Token Recharge Flowchart

Notes

• 【10. User Payment Successful】: Triggered by the success callback of wx.requestVirtualPayment. It may be lost if, for example, WeChat exits abnormally.
• It is recommended to implement either [Payment Push Branch] or [Payment Polling Branch]. Using both together ensures a more reliable experience.

# 2.2 Client API

The basic library interface wx.requestVirtualPayment is used to initiate virtual payments. It includes logic for placing orders and initiating payment processes.

# 2.3 Server API

# Token-related

# Gadget-related

# Orders and Billing

# Fund Management

# Advertising Funds

# Complaint Handling

# 2.4 Message Pushing

# Explanation of Push Response Format

Note: If the push response format is incorrect, WeChat will retry the push up to 15 times.

Currently, three methods are supported:

1. [Recommended] The ErrCode method listed in the documentation

   When the push content is in XML format, the response must also be in XML:

   <xml><ErrCode>0</ErrCode><ErrMsg><![CDATA[success]]></ErrMsg></xml>
   

2. Similarly, if the push content is in JSON format, the response should be in JSON format:

   {"ErrCode":0,"ErrMsg":"success"}
   

3. An empty response or a response indicating “success” equates to ErrCode = 0, indicating success.

# Item Delivery Notification (xpay_goods_deliver_notify)

# Request Parameters

WeChatPayInfo Structure:

GoodsInfo Structure:

TeamInfo Structure:

# Return Parameters

# Token Payment Notification (xpay_coin_pay_notify)

# Request Parameters

WeChatPayInfo Structure:

CoinInfo Structure:

# Response Parameters

# Refund Notification (xpay_refund_notify)

# Request Parameters

**

TeamInfo Structure:

# User Complaint Notification (xpay_complaint_notify)

# Request Parameters

# Response Parameters

# 2.5 Signature Details

Both user-side signatures and payment signatures are utilized in the base library wx.requestVirtualPayment and server APIs.

# Payment Signature

The pseudocode for the signature algorithm is as follows:

paySig = to_hex(hmac_sha256(appKey, uri + '&' + signData))

Parameter Explanation (WeChat API vs Server API):

Refer to the calc_pay_sig function below.

# User-Side Signature

The pseudocode for the signature algorithm is as follows:

signature = to_hex(hmac_sha256(sessionKey, signData))

Parameter Explanation (WeChat API vs Server API):

# 2.6 Referenced Python Script

Taking the call to the query_user_balance interface as an example, the signature calculation is as follows:

#!/usr/bin/python
# -*- coding: utf-8 -*-
""" Example of pay_sig signature algorithm calculation """

import hmac
import hashlib
import json
import time

def calc_pay_sig(uri, post_body, appkey):
    """ pay_sig signature algorithm
      Args:
     uri - The URI part of the requested API, without the query string. Example: /xpay/query_user_balance
          post_body - The data body of the HTTP POST request
          appkey    - The AppKey for the corresponding environment
      Returns:
          The payment request signature, pay_sig
    """
    need_sign_msg = uri + '&' + post_body
    pay_sig = hmac.new(key=appkey.encode('utf-8'), msg=need_sign_msg.encode('utf-8'),
                       digestmod=hashlib.sha256).hexdigest()
    return pay_sig

def calc_signature(post_body, session_key):
    """ Signature algorithm for user login state
      Args:
          post_body   - The data body of the HTTP POST request
          session_key - The valid session_key for the current user, obtained from the auth.code2Session interface
      Returns:
          The signature for the user login state
    """
    need_sign_msg = post_body
    signature = hmac.new(key=session_key.encode('utf-8'), msg=need_sign_msg.encode('utf-8'),
                       digestmod=hashlib.sha256).hexdigest()
    return signature

# Ensure the uri does not contain parameters, i.e., remove “?” and everything after it
# For the basic library’s wx.requestVirtualPayment, the uri is fixed as requestVirtualPayment
uri = '/xpay/query_user_balance'

# The appkey here is a placeholder. In practice, it should be replaced with the actual AppKey based on the payment environment (specified by the env parameter)
appkey = "12345"

# Note: The JSON serialization result may vary depending on the language or version. 
# Therefore, for stability purposes, an example using one of the serialized versions is provided. 
# In practice, ensure that the `post_body` used for signing matches the actual HTTP request body.

"""
# Different APIs require different Post Body parameters. Here, we use the `query_user_balance` API as an example (matching the URI).
post_body = json.dumps({
    "openid": "xxx",
    "user_ip": "127.0.0.1",
    "env": 0
})
"""
post_body = '{"openid": "xxx", "user_ip": "127.0.0.1", "env": 0}'

# Step 1: Calculate the pay_sig (payment request signature algorithm)
pay_sig = calc_pay_sig(uri, post_body, appkey)
print("pay_sig:", pay_sig)

# If the returned pay_sig does not match, follow these steps to troubleshoot:
# 1. Verify the algorithm: Ensure that `uri`, `post_body`, and `appkey` remain constant, and that your signature matches the output of `calc_pay_sig`.
# 2. Confirm the parameters:
#    - `uri` should not contain parameters (ignore everything after "?").
#    - `post_body` must be identical to the body sent in the actual HTTP request.
#    - `appkey` must correspond to the environment specified in the request (determined by the `env` parameter).
assert pay_sig == "c37809f27c6d7fd1837ad2500a04512b66b34fd793a39a385fade56dca89a4b5"

# Step 2: Calculate the signature (signature algorithm for logged-in users)
# `session_key` must be a valid session key for the current user (obtain it using the `auth.code2Session` API).
# For simplicity, we use a fixed `session_key` here.
session_key = "9hAb/NEYUlkaMBEsmFgzig=="
signature = calc_signature(post_body, session_key)
print("signature:", signature)

# If the returned signature does not match, refer to the troubleshooting guide below.
assert signature == "089d9e8dc5d308977360c4b79ec600a93d736802802a807d634192328032f6c7"

# 2.7 Payment Functionality on Windows Clients

# Integration Steps

1. Use the wx.getSystemInfo or wx.getDeviceInfo API to retrieve the platform value.
2. Adapt the code to work on Windows as well.
3. Test the functionality on a Windows client using WeChat Developer Tool’s real-device debugging feature.

// Example code for payment functionality compatible with both Android and Windows:
if(wx.getSystemInfoSync().platform == 'android' || wx.getSystemInfoSync().platform == 'windows') {
    wx.requestVirtualPayment({...})
}

The normal payment process for Windows clients is shown in the following image:

An error scenario where the developer hasn’t adapted the code for Windows clients is shown in the following image: