简介

此文档是微信小程序虚拟支付的云端API补充，使用此文档的API需要先安装 uni-pay 插件才能使用，仅 uni-app 项目可用，uni-app-x 项目暂不支持微信支付，也不支持微信小程序虚拟支付

Api 列表

提示：微信虚拟支付有很多API，当前仅支持以下几个常用的API，后面会陆续增加其他API

特别说明

以下API均只能在云端调用，不可以在前端调用

充值代币、道具直购

充值代币 和 道具直购 涉及到前端API，需要搭配 uni-pay 组件使用，详情见 充值代币文档 、道具直购文档

查询用户代币余额

接口名

queryUserBalance

入参说明

参数名	类型	必填	默认值	说明
openid	String	是	-	用户的openid
userIp	String	是	-	用户的ip地址

返回值说明

参数名	类型	说明
balance	Number	代币总余额，包括有价和赠送部分
presentBalance	Number	赠送账户的代币余额
sumSave	Number	累计有价货币充值数量
sumPresent	Number	累计赠送无价货币数量
sumBalance	Number	历史总增加的代币金额
sumCost	Number	历史总消耗代币金额
firstSaveFlag	Boolean	是否满足首充活动标记。0:不满足。1:满足

使用示例

// 引入 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

注意

此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	订单号原样返回

使用示例

// 引入 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

入参说明

参数名	类型	必填	默认值	说明
openid	String	是	-	用户的openid
userIp	String	是	-	用户的ip地址
amount	Number	是	-	退款金额
outTradeNo	String	是	-	订单号
outRefundNo	String	是	-	本次退款单的单号
deviceType	Number	是	-	平台类型1-安卓 2-苹果

返回值说明

参数名	类型	说明
outRefundNo	String	退款订单号

使用示例

// 引入 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);

代币赠送

接口名

presentCurrency

入参说明

参数名	类型	必填	默认值	说明
openid	String	是	-	用户的openid
userIp	String	是	-	用户的ip地址
amount	Number	是	-	退款金额
outTradeNo	String	是	-	订单号
deviceType	Number	是	-	平台类型1-安卓 2-苹果

返回值说明

参数名	类型	说明
balance	String	赠送后用户的代币余额
presentBalance	String	用户收到的总赠送金额
outTradeNo	String	赠送单号

使用示例

// 引入 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);