# 1.产品介绍

为保障用户权益，提高交易安全，平台将向”微短剧“类小程序提供虚拟支付能力，开发者可通过小程序管理后台--虚拟支付模块，开通一个新的微信支付商户号，使用账单查询、资金提现等服务。平台将以通过该支付能力产生的支付金额为结算基数，按一定费率收取技术服务费。

本功能暂不开放苹果iOS系统App内购买（In-App Purchase）方式，仅向安卓及其他手机系统提供，如有疑问可联系客服进行沟通.

若测试请先使用沙箱环境，若使用现网环境，平台将收取相关技术服务费

注意事项：开发者请在2.19.2 或以上版本基础库中调用

# 1.1.开通条件

●主体类型为已认证小程序

●小程序类型为企业小程序

●小程序运营资质为“文娱-微短剧“类目

●小程序主体信息完备（若有缺陷请使用平台提供的修改链接修正）

# 1.2.开通入口

当小程序完成资质申请并且通过获得“微短剧”类目后，点击mp左边栏【虚拟支付】即可前往开通页面进行开通。

若当前账户满足开通条件后，点击【开通】按钮进行协议签署及资料上传，开通新的商户号。

# 1.3.开通流程

# 第一步：阅读协议

进行协议阅读虚拟支付协议，勾选【我已阅读并同意上述条款】后进入下一步

# 第二步：提交商户相关资料开通商户号

填写企业的营业执照，提现账户及支付管理员

# 第三步：账户状态查询及资料审核

完成商户资料提交，此时可在界面等待查询账户状态，审核一般需要1-7个工作日，审核状态下次进入时即可查看。

# 第四步：进行账户验证

进行账户验证（若支付管理员配置为公司法人则跳过该步骤）

# 第五步：扫码签约

扫码完成签约 签约完成后，资料将提交进行审核，开发者可离开当前页面。

注意由于“账户验证”，“签约”不一定会即时完成，开发者可退出页面，后续再次进入将继续延续之前的配置。

等待约1-2个工作日后回到虚拟支付模块，可以看到状态为已签约，或直接进入了商户管理的模块则表示已完成了签约，成功开通了二级商户号。

# 第六步：进入商户管理后台进行账单/订单查询，代币/道具配置及资金管理

当完成了前续动作后，虚拟支付栏目将呈现为全新的商户管理模块，我们搭建了开发者的商户后台，允许开发者在后台进行基础信息配置，代币及道具配置和管理（开发者可以自行选择使用道具或者代币来管理自己的商品）

详细的功能解释如下

# 基本配置：包含三个模块

# 基础配置：开发者可在该界面查看自身基础配置信息（包括appid/offerid/appkey，发货订阅等）

# 代币配置：开发者可在该界面配置代币，输入代币名称并且设置代币兑换比例进行保存 （请注意一旦发布无法修改！请注意代币名称符合相关法律法规要求）

# 道具管理：开发者可在该界面上传道具至开发版本及发布至现网版本，可支持编辑保存后发布，并且可以查看发货推送配置 （输入的道具名称需符合相关法律法规要求）

# 资金管理：

可在此界面进行账户余额查询和提现，查看每日账单具体情况，包括订单号，开发者收益等，也可以查看账单明细（后期将支持下载功能）

注：待结算金额指的系尚未进行分账的金额，未扣除技术服务费

结算周期:T+3，即开发者完成一笔订单后，资金将会冻结，3日后进行分帐

# 交易订单：

可在此界面查询订单状况，包括代币/道具订单的交易及发货情况，可进行退款操作（后期将支持下载功能）

# 广告金：

平台将设置广告金政策以支持开发者的广告投放，商户可在虚拟支付--广告金管理界面查看平台向商户赠送的广告金。

# 2.开发流程

# 2.1.时序图

# 道具直购流程图

# 道具直购注意事项

• 【7. 用户支付成功】: 由wx.requestVirtualPayment的success回调触发，可能会丢失，比如微信异常退出
• 【发货推送分支】和【发货轮训分支】至少实现一个，两个结合的方式，可提供更可靠的道具直购体验

# 代币充值流程图

# 代币充值注意事项

• 【10. 用户支付成功】 : 由wx.requestVirtualPayment的success回调触发，可能会丢失，比如微信异常退出
• 【支付推送分支】和【支付轮训分支】至少实现一个，两个结合起来会更可靠

# 2.2.wx API

基础库接口wx.requestVirtualPayment用于发起米大师虚拟支付，内部会包含下单，拉起支付逻辑

# 2.3.服务器API

# 用户态签名

签名参数为signature，加在query后面，例如接口地址是：https://api.weixin.qq.com/xpay/query_user_balance?access_token=xxxx，加上签名后则需要传https://api.weixin.qq.com/xpay/query_user_balance?access_token=xxxx&signature=xxx

# 支付签名

签名参数为pay_sig，加在query后面，例如接口地址是：https://api.weixin.qq.com/xpay/query_user_balance?access_token=xxxx，加上签名后则需要传https://api.weixin.qq.com/xpay/query_user_balance?access_token=xxxx&pay_sig=xxx

# 错误码

# query_user_balance

# 地址

https://api.weixin.qq.com/xpay/query_user_balance?access_token=xxx&pay_sig=xxx

# 描述

查询用户代币余额

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# 备注

1. 需要用户态签名与支付签名

# currency_pay

# 地址

https://api.weixin.qq.com/xpay/currency_pay?access_token=xxx&pay_sig=xxx&signature=xxx

# 描述

扣减代币（一般用于代币支付）

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# 备注

1. 使用用户态签名与支付签名

# query_order

# 地址

https://api.weixin.qq.com/xpay/query_order?access_token=xxx&pay_sig=xxx

# 描述

查询创建的订单（现金单，非代币单）

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

其中order的内容如下：

# 备注

1. 使用支付签名

# cancel_currency_pay

# 地址

https://api.weixin.qq.com/xpay/cancel_currency_pay?access_token=xxx&pay_sig=xxx

# 描述

代币支付退款(currency_pay接口的逆操作)

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# 备注

1. 需要支付签名与用户态签名

# notify_provide_goods

# 地址

https://api.weixin.qq.com/xpay/notify_provide_goods?access_token=xxx&pay_sig=xxx

# 描述

通知已经发货完成（只能通知现金单）,正常通过xpay_goods_deliver_notify消息推送返回成功就不需要调用这个api接口。这个接口用于异常情况推送不成功时手动将单改成已发货状态

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# present_currency

# 地址

https://api.weixin.qq.com/xpay/present_currency?access_token=xxx&pay_sig=xxx

# 描述

代币赠送接口，由于目前不支付按单号查赠送单的功能，所以当需要赠送的时候可以一直重试到返回0或者返回268490004（重复操作）为止

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# download_bill

# 地址

https://api.weixin.qq.com/xpay/download_bill?access_token=xxx&pay_sig=xxx

# 描述

用于下载小程序账单，第一次调用触发生成下载url，可以间隔轮训来获取最终生成的下载url。

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# 备注

1. 使用支付签名

# refund_order

# 地址

https://api.weixin.qq.com/xpay/refund_order?access_token=xxx&pay_sig=xxx

# 描述

对使用jsapi接口下的单进行退款，此接口只是启动退款任务成功，启动后需要调用query_order接口来查询退款单状态，等状态变成退款完成后即为最终成功

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# 备注

1. 使用支付签名

# create_withdraw_order

# 地址

https://api.weixin.qq.com/xpay/create_withdraw_order?access_token=xxx&pay_sig=xxx

# 描述

创建提现单

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# 备注

1. 使用支付签名

# query_withdraw_order

# 地址

https://api.weixin.qq.com/xpay/query_withdraw_order?access_token=xxx&pay_sig=xxx

# 描述

创建提现单

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# 备注

1. 使用支付签名

# start_upload_goods

# 地址

https://api.weixin.qq.com/xpay/start_upload_goods?access_token=xxx&pay_sig=xxx

# 描述

启动批量上传道具任务

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

upload_item的每一项内容如下：

# 返回参数

# 备注

1. 使用支付签名

# query_upload_goods

# 地址

https://api.weixin.qq.com/xpay/query_upload_goods?access_token=xxx&pay_sig=xxx

# 描述

查询批量上传道具任务

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

upload_item的每一项内容如下：

# 备注

1. 使用支付签名

# start_publish_goods

# 地址

https://api.weixin.qq.com/xpay/start_publish_goods?access_token=xxx&pay_sig=xxx

# 描述

启动批量发布道具任务

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

publish_item的每一项内容如下：

# 返回参数

# 备注

1. 使用支付签名

# query_publish_goods

# 地址

https://api.weixin.qq.com/xpay/query_publish_goods?access_token=xxx&pay_sig=xxx

# 描述

查询批量发布道具任务

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

upload_item的每一项内容如下：

# 备注

1. 使用支付签名

# query_biz_balance

# 地址

https://api.weixin.qq.com/xpay/query_biz_balance?access_token=xxx&pay_sig=xxx

# 描述

查询商家账户里的可提现余额

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

其中balance_available内容如下：

# 备注

1. 使用支付签名

# query_transfer_account

# 地址

https://api.weixin.qq.com/xpay/query_transfer_account?access_token=xxx&pay_sig=xxx

# 描述

查询广告金充值账户

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

acct_list的每一项内容如下：

# query_adver_funds

# 地址

https://api.weixin.qq.com/xpay/query_adver_funds?access_token=xxx&pay_sig=xxx

# 描述

查询广告金发放记录

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

filter的每一项内容如下：

# 返回参数

adver_funds_list的每一项内容如下：

# create_funds_bill

# 地址

https://api.weixin.qq.com/xpay/create_funds_bill?access_token=xxx&pay_sig=xxx

# 描述

充值广告金

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# bind_transfer_accout

# 地址

https://api.weixin.qq.com/xpay/bind_transfer_accout?access_token=xxx&pay_sig=xxx

# 描述

绑定广告金充值账户

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# query_funds_bill

# 地址

https://api.weixin.qq.com/xpay/query_funds_bill?access_token=xxx&pay_sig=xxx

# 描述

查询广告金充值记录

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

filter的每一项内容如下：

# 返回参数

bill_list的每一项内容如下：

# query_recover_bill

# 地址

https://api.weixin.qq.com/xpay/query_recover_bill?access_token=xxx&pay_sig=xxx

# 描述

查询广告金回收记录

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

filter的每一项内容如下：

# 返回参数

bill_list的每一项内容如下：

# get_complaint_list

# 地址

https://api.weixin.qq.com/xpay/get_complaint_list?access_token=xxx&pay_sig=xxx

# 描述

获取投诉列表

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

其中complaints内容如下：

其中complaint_order_info的每一期内容为：

其中complaint_media_list每一项内容为：

其中service_order_info每一项内容为：

# 备注

1. 使用支付签名

# get_complaint_detail

# 地址

https://api.weixin.qq.com/xpay/get_complaint_detail?access_token=xxx&pay_sig=xxx

# 描述

获取投诉详情

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# 备注

1. 使用支付签名

# get_negotiation_history

# 地址

https://api.weixin.qq.com/xpay/get_negotiation_history?access_token=xxx&pay_sig=xxx

# 描述

获取协商历史

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

其中history的每一项内容为：

其中complaint_media_list每一项的内容如下：

# 备注

1. 使用支付签名

# response_complaint

# 地址

https://api.weixin.qq.com/xpay/response_complaint?access_token=xxx&pay_sig=xxx

# 描述

回复用户

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# 备注

1. 使用支付签名

# complete_complaint

# 地址

https://api.weixin.qq.com/xpay/complete_complaint?access_token=xxx&pay_sig=xxx

# 描述

完成投诉处理

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# 备注

1. 使用支付签名

# upload_vp_file

# 地址

https://api.weixin.qq.com/xpay/upload_vp_file?access_token=xxx&pay_sig=xxx

# 描述

上传媒体文件（如图片，凭证等）

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# 备注

1. 使用支付签名

# get_upload_file_sign

# 地址

https://api.weixin.qq.com/xpay/get_upload_file_sign?access_token=xxx&pay_sig=xxx

# 描述

获取微信支付反馈投诉图片的签名头部

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# 备注

1.使用支付签名

2.微信支付的图片资源下载需要在http请求的时候必填以下3个头部信息，否则会报错

• Authorization，签名验证，由本接口的sign返回
• Accept，值需要是"application/json"
• User-Agent，UA不能为空

# download_adverfunds_order

# 地址

https://api.weixin.qq.com/xpay/download_adverfunds_order?access_token=xxx&pay_sig=xxx

# 描述

下载广告金对应的商户订单信息

# 请求方法

POST ， 请求参数为json字符串，Content-Type为application/json

# 请求参数

# 返回参数

# 备注

1. 当前仅支持通用赠送广告金对应订单下载
2. 第一次调用触发生成下载url，可以间隔轮训来获取最终生成的下载url。

# 消息推送

# 推送响应格式说明

注：如果推送响应格式不对，微信会重新推送，最多试15次

目前支持三种方式：

1. 【推荐】文档中列的ErrCode方式

推送内容为xml格式时，响应内容需要是xml格式

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

同理推送内容为json格式时，响应内容需要是json格式

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

2. 相应内容为空 或者success，表示成功（等价于第一种的ErrCode = 0）

# 道具发货推送xpay_goods_deliver_notify

# 请求参数

WeChatPayInfo内容如下：

GoodsInfo内容如下：

# 返回参数

# 代币支付推送xpay_coin_pay_notify

# 请求参数

WeChatPayInfo内容如下：

CoinInfo内容如下：

# 返回参数

# 退款推送xpay_refund_notify

# 请求参数

# 返回参数

# 2.4.签名详解

用户态签名和支付签名在基础库wx.requestVirtualPayment和服务器API中都会涉及

# 支付签名

签名算法伪代码为：

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

可参考下面的calc_pay_sig函数

# 用户态签名

签名算法伪代码为：

signature = to_hex(hmac_sha256(sessionKey,signData))

# 参考的python脚本

以调用query_user_balance接口为例，签名计算如下：

#!/usr/bin/python
# -*- coding: utf-8 -*-
""" pay_sig签名算法计算示例 """

import hmac
import hashlib
import json
import time

def calc_pay_sig(uri, post_body, appkey):
    """ pay_sig签名算法
      Args:
     uri - 当前请求的API的uri部分，不带query_string 例如：/xpay/query_user_balance
          post_body - http POST的数据包体
          appkey    - 对应环境的AppKey
      Returns:
          支付请求签名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签名算法
      Args:
          post_body   - http POST的数据包体
          session_key - 当前用户有效的session_key，参考auth.code2Session接口
      Returns:
          用户登录态签名signature
    """
    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

# uri，切记不可带参数，即去掉"?"及后面的部分
# 如果是基础库的wx.requestVirtualPayment，uri固定为requestVirtualPayment
uri = '/xpay/query_user_balance'

# 此处appkey为假设值，实际使用应根据支付环境(env参数)替换为对应的AppKey
appkey = "12345"

# 注意：JSON数据序列化结果，不同语言/版本结果可能不同
# 所以示例为了保证稳定性，直接用其中一个序列化的版本
# 实际使用时只需要保证，参与签名的post_body和真正发起http请求的一致即可
"""
# 不同接口要求的Post Body参数不一样，此处以query_user_balance接口为例(和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}'

# step1. pay_sig签名计算（支付请求签名算法）
pay_sig = calc_pay_sig(uri, post_body, appkey)
print("pay_sig:", pay_sig)

# 若实际请求返回pay_sig签名不对，根据以下步骤排查：
# 1. 确认算法：uri、post_body、appkey写死以上参数，确保你的签名算法和示例calc_pay_sig结果完全一致
# 2. 确认参数：
#    - uri不可带参数（即"?"及后续部分全部舍去）
#    - post_body必须和真正发起HTTP请求的post body完全一致
#    - appkey必须是与请求中对应的环境匹配（env参数决定）
assert pay_sig == "c37809f27c6d7fd1837ad2500a04512b66b34fd793a39a385fade56dca89a4b5"

# step2. signature签名计算（用户登录态签名算法）
# session_key需要为当前用户有效session_key（参考auth.code2Session接口获取）
# 此处写死方便复现算法
session_key = "9hAb/NEYUlkaMBEsmFgzig=="
signature = calc_signature(post_body, session_key)
print("signature:", signature)

# 若实际请求返回signature签名不对，参考随后的“90010-signature签名错误问题排查思路”进行排查
assert signature == "089d9e8dc5d308977360c4b79ec600a93d736802802a807d634192328032f6c7"

# 3.版本更新日志

1.0.13

1. 广告金类型fund_type增加定向激励类型

1.0.12

1. 新增下载广告金对应商户订单信息api: download_adverfunds_order

1.0.11

1. query_transfer_account返回结构里新增账户审核、绑定状态和错误信息字段:state、bind_result、error_msg

1.0.10

1. get_complaint_list返回结构里的payer_phone改为明文
2. get_complaint_list返回结构里新增wxa_out_trade_no , wx_order_id字段

1.0.9

1. 新增投诉图片签名获取接口get_upload_file_sign
2. 修改get_complaint_detail接口的返回字段为complaint，与接口实际返回一致

1.0.8

1. 新增广告金充值和回收查询 api：query_funds_bill，query_recover_bill

1.0.7

1. query_adver_funds返回增加 fund_id 字段

1.0.6

1. 新增投诉相关api，get_complaint_list、get_complaint_detail、get_negotiation_history、response_complaint、complete_complaint、upload_vp_file

1.0.5

1. 新增广告金发放原因字段筛选和充值，支持通用赠送广告金查询和充值

1.0.4

1. 新增query_order里的查单状态
2. refund_order接口改成异步逻辑并支持t+3以上的单进行退款（需要在180天内），调用成功只是启动退款成功，最终结果需要查询
3. 新增退款通知

1.0.3

1. 新增广告金充值能力
2. 新增广告金api能力，包括：查询广告金充值帐户、查询广告金发放记录、充值广告金、绑定广告金充值帐户。

1.0.2

1. query_order新增结算状态字段
2. 新增query_biz_balance接口查询提现余额

1.0.1

1. 新增《推送响应格式说明》
2. 新增全额提现能力
3. 基础库版本支持到2.19.2

1.0.0

1. 新增虚拟支付能力