docs: 新增微信小程序虚拟支付文档、uni-pay-x文档

docs/_sidebar.md

@@ -103,8 +103,10 @@
   * [uni-admin](admin.md)
   * [uni-upgrade-center App升级中心](upgrade-center.md)
   * uni-pay 统一支付```{"collapsable": true}```
-  * * [uni-pay 云端一体页面模板](uni-pay.md)
-  * * [uni-pay 公共模块](unipay.md)
+  * * [uni-pay 云端一体页面模板 uni-app](uni-pay/uni-app.md)
+  * * [uni-pay 云端一体页面模板 uni-app-x](uni-pay/uni-app-x.md)
+  * * [uni-pay 公共模块](uni-pay/uni-pay-common.md)
+  * * [uni-pay 微信小程序虚拟支付](uni-pay/wxpay-virtual.md)
   * [uni-cms 内容管理](uni-cms.md)
   * [uni-ai-chat ai聊天示例](uni-ai-chat.md)
   * [uni-im 即时通信](uni-im.md)

docs/uni-pay/wxpay-virtual.md

+## 简介
+
+此文档是微信小程序虚拟支付的云端API补充，使用此文档的API需要先安装 [uni-pay](./uni-app.md) 插件才能使用，仅 uni-app 项目可用，uni-app-x 项目暂不支持微信支付，也不支持微信小程序虚拟支付
+
+## Api 列表
+
+提示：微信虚拟支付有很多API，当前仅支持以下几个常用的API，后面会陆续增加其他API
+
+### 充值代币、道具直购
+
+`充值代币` 和 `道具直购` 涉及到前端API，需要搭配 `uni-pay` 组件使用，详情见 [充值代币文档](./uni-app.md#short-series-coin) 、[道具直购文档](./uni-app.md#short-series-goods)
+
+### 查询用户代币余额@queryUserBalance
+
+**接口名**
+
+`queryUserBalance`
+
+**入参说明**
+
+|    参数名     |  类型  |  必填  | 默认值 |    说明    |
+| :-----------: | :----: | :---:| :----: |:--------: |
+| openid        | String |  是  |   -    | 用户的openid |  
+| userIp        | String |  是  |   -    | 用户的ip地址 | 
+
+**返回值说明**
+
+|    参数名         |  类型  |    说明    |
+| :-----------:    | :----: | :--------: |
+| balance          | Number |  代币总余额，包括有价和赠送部分|  
+| presentBalance   | Number |  赠送账户的代币余额  | 
+| sumSave          | Number | 累计有价货币充值数量   | 
+| sumPresent       | Number | 累计赠送无价货币数量   | 
+| sumBalance       | Number | 历史总增加的代币金额   | 
+| sumCost          | Number | 历史总消耗代币金额  | 
+| firstSaveFlag    | Boolean| 是否满足首充活动标记。0:不满足。1:满足   | 
+
+**使用示例**
+
+```js
+// 引入 uni-pay-co 云对象
+const uniPayCo = uniCloud.importObject("uni-pay-co");
+// 请求微信虚拟支付API
+let res = await uniPayCo.requestWxpayVirtualApi({
+	method: "queryUserBalance", // 请求方法
+	// 请求参数
+	data: {
+		openid: "", // 用户openid
+		userIp: "", // 用户IP
+	}
+});
+console.log('res: ', res);
+```
+
+### 扣减代币（一般用于代币支付）@currencyPay
+
+**接口名**
+
+`currencyPay`
+
+**注意**
+
+此API需要用到用户的 `sessionKey`，如果用户长时间没有活跃过小程序，则无法请求扣减代币接口，会报用户sessionKey不存在或已过期，请重新登录的错误
+
+微信小程序虚拟支付退款后，如果退款的是代币充值订单，则退款成功后原本用户充值的代币不会自动扣减，需要执行此API才能扣减，而用户长时间没有活跃过小程序，则无法请求扣减代币接口，因此需要注意退款时间，时间相隔太长可能会导致出现无法扣减代币的尴尬情况
+
+**入参说明**
+
+|    参数名     |  类型  |  必填  | 默认值 |    说明    |
+| :-----------: | :----: | :---:| :----: |:--------: |
+| openid        | String |  是  |   -    | 用户的openid |  
+| userIp        | String |  是  |   -    | 用户的ip地址 | 
+| amount        | Number |  是  |   -    | 支付的代币数量 | 
+| outTradeNo    | String |  是  |   -    | 订单号 | 
+| deviceType    | Number |  是  |   -    | 平台类型1-安卓 2-苹果 | 
+| payitem       | String |  否  |   -    | 物品信息。记录到账户流水中。如:[{"productid":"物品id", "unit_price": 单价, "quantity": 数量}],注意只能是json字符串格式 | 
+| remark        | String |  否  |   -    | 备注 | 
+| sessionKey    | String |  否  |   -    | 用户的sessionKey，不传会尝试自动获取 | 
+
+**返回值说明**
+
+|    参数名         |  类型  |    说明    |
+| :-----------:    | :----: | :--------: |
+| balance          | Number |  总余额，包括有价和赠送部分|  
+| usedPresentAmount   | Number |  使用赠送部分的代币数量  | 
+| outTradeNo          | String | 订单号原样返回   | 
+
+**使用示例**
+
+```js
+// 引入 uni-pay-co 云对象
+const uniPayCo = uniCloud.importObject("uni-pay-co");
+let outTradeNo = "test-" + Date.now(); // 商户订单号
+// 请求微信虚拟支付API
+let res = await uniPayCo.requestWxpayVirtualApi({
+	method: "currencyPay", // 请求方法
+	// 请求参数
+	data: {
+		openid: "", // 用户openid
+		userIp: "", // 用户IP
+		amount: 1, // 扣减的代币数量
+		outTradeNo, // 商户订单号
+		payitem: JSON.stringify([{ "productid": "test001", "unit_price": 1, "quantity": 1 }]),
+		remark: "备注",
+		deviceType: 1, // 平台类型1-安卓 仅支持传1
+	}
+});
+console.log('res: ', res);
+```
+
+### 代币支付退款（currencyPay接口的逆操作）@cancelCurrencyPay
+
+**接口名**
+
+`cancelCurrencyPay`
+
+**入参说明**
+
+|    参数名     |  类型  |  必填  | 默认值 |    说明    |
+| :-----------: | :----: | :---:| :----: |:--------: |
+| openid        | String |  是  |   -    | 用户的openid |  
+| userIp        | String |  是  |   -    | 用户的ip地址 | 
+| amount        | Number |  是  |   -    | 退款金额 | 
+| outTradeNo    | String |  是  |   -    | 订单号 | 
+| outRefundNo    | String |  是  |   -    | 本次退款单的单号 | 
+| deviceType    | Number |  是  |   -    | 平台类型1-安卓 2-苹果 | 
+
+**返回值说明**
+
+|    参数名         |  类型  |    说明    |
+| :-----------:    | :----: | :--------: |
+| outRefundNo      | String |  退款订单号|  
+
+**使用示例**
+
+```js
+// 引入 uni-pay-co 云对象
+const uniPayCo = uniCloud.importObject("uni-pay-co");
+let outTradeNo = "";
+let lastFourDigits = Date.now().toString().substr(-4);
+// 请求微信虚拟支付API
+let res = await uniPayCo.requestWxpayVirtualApi({
+	method: "cancelCurrencyPay", // 请求方法
+	// 请求参数
+	data: {
+		openid: "", // 用户openid
+		userIp: "", // 用户IP
+		amount: 1, // 撤回扣减的代币数量
+		outTradeNo, // 商户订单号
+		outRefundNo: `${outTradeNo}-${lastFourDigits}`,
+		deviceType: 1, // 平台类型1-安卓 仅支持传1
+	}
+});
+console.log('res: ', res);
+```
+
+### 代币赠送（currencyPay接口的逆操作）@presentCurrency
+
+**接口名**
+
+`presentCurrency`
+
+**入参说明**
+
+|    参数名     |  类型  |  必填  | 默认值 |    说明    |
+| :-----------: | :----: | :---:| :----: |:--------: |
+| openid        | String |  是  |   -    | 用户的openid |  
+| userIp        | String |  是  |   -    | 用户的ip地址 | 
+| amount        | Number |  是  |   -    | 退款金额 | 
+| outTradeNo    | String |  是  |   -    | 订单号 | 
+| deviceType    | Number |  是  |   -    | 平台类型1-安卓 2-苹果 | 
+
+**返回值说明**
+
+|    参数名         |  类型  |    说明    |
+| :-----------:    | :----: | :--------: |
+| balance          | String |  赠送后用户的代币余额|  
+| presentBalance   | String |  用户收到的总赠送金额|  
+| outTradeNo       | String |  赠送单号|  
+
+**使用示例**
+
+```js
+// 引入 uni-pay-co 云对象
+const uniPayCo = uniCloud.importObject("uni-pay-co");
+let outTradeNo = "test-" + Date.now(); // 商户订单号
+// 请求微信虚拟支付API
+let res = await uniPayCo.requestWxpayVirtualApi({
+	method: "presentCurrency", // 请求方法
+	// 请求参数
+	data: {
+		openid: "", // 用户openid
+		userIp: "", // 用户IP
+		amount: 1, // 赠送用户代币数量
+		outTradeNo, // 商户订单号
+		deviceType: 1, // 平台类型1-安卓 仅支持传1
+	}
+});
+console.log('res: ', res);
+```
\ No newline at end of file