@dcloudio/uni-pay v1.0.2

简介

uniPay是适用于uniCloud统一支付接口，目前支持支付宝和微信的支付 api（小程序端和 App 端）。使用uniPay可以让你不用为每个平台单独写一套逻辑，业务代码更简洁，逻辑更清晰。

须知

• uniPay 对入参和返回值均做了驼峰转化，开发者在对照微信支付或者支付宝支付对应的文档时需要注意。
• 特殊参数appId、mchId需注意大小写
• 所有金额被统一为以分为单位
• 为避免无关参数干扰此文档仅列举必填参数，其余参数请参照微信支付-小程序、微信支付-App、支付宝支付-小程序、支付宝支付-App
• 微信支付沙箱环境不支持小程序支付，另外此沙箱环境只可以跑微信提供的测试用例不可以随意测试
• 无论是微信还是支付宝，沙箱环境都不确保稳定，如果使用沙箱的过程中遇到疑难问题建议切换成正式环境测试

引入 uniPay

开发者可以自行选择是从插件市场导入还是从 npm 安装，引入方式略有不同，请看下面示例

// 插件市场导入
const uniPay = require('uni-pay')

// npm安装
const uniPay = require('@dcloudio/uni-pay')

初始化

进行初始化操作返回 uniPay 实例

微信支付

入参说明

const uniPayIns = uniPay.initWeixin({
  appId: 'your appId',
  mchId: 'your mchId',
  key: 'you parterner key',
  pfx: fs.readFileSync('/path/to/your/pfxfile'), // p12文件路径，使用微信退款时需要，需要注意的是阿里云目前不支持以相对路径读取文件，请使用绝对路径的形式
})

支付宝小程序

入参说明

const uniPayIns = uniPay.initAlipay({
  appId: 'your appId',
  privateKey: 'your privateKey',
  alipayPublicKey: 'you alipayPublicKey', // 使用支付时需传递此值做返回结果验签
})

Api 列表

获取支付参数

uniPayIns.getOrderInfo，此接口仅支持微信小程序、支付宝小程序、App 平台

入参说明

返回值说明

使用示例

// 云函数 - getOrderInfo
exports.main = async function (event,context) {
	let	orderInfo = await uniPayIns.getOrderInfo({
		openid: 'user openid',
		subject: '订单标题', // 微信支付时不可填写此项
		body: '商品描述',
		outTradeNo: '商户订单号',
		totalFee: 1, // 金额，单位分
		notifyUrl: 'https://xxx.xx' // 支付结果通知地址
	})
	return {
		orderInfo
	}
}

// 客户端
uniCloud.callFunction({
	name: 'getOrderInfo',
	success(res) {
		uni.requestPayment({
      // #ifdef APP-PLUS
      provider: selectedProvider, // App端此参数必填，可以通过uni.getProvider获取
      // #endif
      // #ifdef MP-WEIXIN
      ...res.result.orderInfo,
      // #endif
      // #ifdef APP-PLUS || MP-ALIPAY
      orderInfo: res.result.orderInfo,
      // #endif
			...res.result.orderInfo
			success(){},
			fail(){}
		})
	}
})

查询订单

uniPayIns.orderQuery, 根据商户订单号或者平台订单号查询订单信息，主要用于未接收到支付通知时可以使用此接口进行支付结果验证

入参说明

返回值说明

使用示例

exports.main = async function (event) {
  let res = await uniPayIns.orderQuery({
    outTradeNo: 'outTradeNo',
  })
  return res
}

关闭订单

uniPayIns.closeOrder，用于交易创建后，用户在一定时间内未进行支付，可调用该接口直接将未付款的交易进行关闭，避免重复支付。

注意

• 微信支付：订单生成后不能马上调用关单接口，最短调用时间间隔为 5 分钟。

入参说明

返回值说明

使用示例

exports.main = async function (event) {
  let res = await uniPayIns.closeOrder({
    outTradeNo: 'outTradeNo',
  })
  return res
}

撤销订单

uniPayIns.cancelOrder，此接口仅支付宝支持，支付交易返回失败或支付系统超时，调用该接口撤销交易。如果此订单用户支付失败，支付宝系统会将此订单关闭；如果用户支付成功，支付宝系统会将此订单资金退还给用户。 注意：只有发生支付系统超时或者支付结果未知时可调用撤销，其他正常支付的单如需实现相同功能请调用申请退款 API。提交支付交易后调用【查询订单 API】，没有明确的支付结果再调用【撤销订单 API】。

入参说明

返回值说明

使用示例

exports.main = async function (event) {
  let res = await uniPayIns.cancelOrder({
    outTradeNo: 'outTradeNo',
  })
  return res
}

申请退款

uniPayIns.refund,当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家。

微信支付注意事项

1. 交易时间超过一年的订单无法提交退款
2. 微信支付退款支持单笔交易分多次退款，多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。 一笔退款失败后重新提交，请不要更换退款单号，请使用原商户退款单号
3. 请求频率限制：150qps，即每秒钟正常的申请退款请求次数不超过 150 次，错误或无效请求频率限制：6qps，即每秒钟异常或错误的退款申请请求不超过 6 次
4. 每个支付订单的部分退款次数不能超过 50 次
5. 如果同一个用户有多笔退款，建议分不同批次进行退款，避免并发退款导致退款失败

入参说明

返回值说明

使用示例

exports.main = async function (event) {
  let res = await uniPayIns.refund({
    outTradeNo: '商户订单号',
    outRefundNo: '商户退款单号', // 支付宝可不填此项
    totalFee: 1, // 订单总金额，支付宝可不填此项
    refundFee: 1, // 退款总金额
  })
  return res
}

查询退款

uniPayIns.refundQuery，提交退款申请后，通过调用该接口查询退款状态。

入参说明

注意

• outRefundNo为使用支付宝请求退款接口时，传入的商户退款单号。如果在退款请求时未传入，则该值为创建交易时的商户订单号即outTradeNo

返回值说明

refundItem 说明

couponItem 说明

refundRoyaltysItem 说明

使用示例

exports.main = async function (event) {
  let res = await uniPayIns.refundQuery({
    outTradeNo: '商户订单号',
    outRefundNo: '商户退款单号', // 支付宝必填
  })
  return res
}

下载交易账单

uniPayIns.downloadBill，商户可以通过该接口下载历史交易清单。仅微信支付支持

注意：

1. 微信侧未成功下单的交易不会出现在对账单中。支付成功后撤销的交易会出现在对账单中，跟原支付单订单号一致；
2. 微信在次日 9 点启动生成前一天的对账单，建议商户 10 点后再获取；
3. 对账单中涉及金额的字段单位为“元”。
4. 对账单接口只能下载三个月以内的账单。
5. 对账单是以商户号纬度来生成的，如一个商户号与多个 appid 有绑定关系，则使用其中任何一个 appid 都可以请求下载对账单。对账单中的 appid 取自交易时候提交的 appid，与请求下载对账单时使用的 appid 无关。

入参说明

返回值说明

content示例如下

当日所有订单 交易时间,公众账号 ID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,微信退款单号,商户退款单号,退款金额, 代金券或立减优惠退款金额，退款类型，退款状态,商品名称,商户数据包,手续费,费率

当日成功支付的订单 交易时间,公众账号 ID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额, 代金券或立减优惠金额,商品名称,商户数据包,手续费,费率

当日退款的订单 交易时间,公众账号 ID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额, 代金券或立减优惠金额,退款申请时间,退款成功时间,微信退款单号,商户退款单号,退款金额, 代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率

从第二行起，为数据记录，各参数以逗号分隔，参数前增加`符号，为标准键盘 1 左边键的字符，字段顺序与表头一致。

倒数第二行为订单统计标题，最后一行为统计数据

总交易单数，总交易额，总退款金额，总代金券或立减优惠退款金额，手续费总金额

举例如下：

交易时间,公众账号ID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,微信退款单号,商户退款单号,退款金额,代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率
`2014-11-10 16：33：45,`wx2421b1c4370ec43b,`10000100,`0,`1000,`1001690740201411100005734289,`1415640626,`085e9858e3ba5186aafcbaed1,`MICROPAY,`SUCCESS,`OTHERS,`CNY,`0.01,`0.0,`0,`0,`0,`0,`,`,`被扫支付测试,`订单额外描述,`0,`0.60%
`2014-11-10 16：46：14,`wx2421b1c4370ec43b,`10000100,`0,`1000,`1002780740201411100005729794,`1415635270,`085e9858e90ca40c0b5aee463,`MICROPAY,`SUCCESS,`OTHERS,`CNY,`0.01,`0.0,`0,`0,`0,`0,`,`,`被扫支付测试,`订单额外描述,`0,`0.60%
总交易单数,总交易额,总退款金额,总代金券或立减优惠退款金额,手续费总金额
`2,`0.02,`0.0,`0.0,`0

使用示例

exports.main = async function (event) {
  let res = await uniPayIns.downloadBill({
    billDate: '20200202',
  })
  return res
}

下载资金账单

uniPayIns.downloadFundflow,商户可以通过该接口下载自 2017 年 6 月 1 日起的历史资金流水账单。仅微信支持

说明：

1. 资金账单中的数据反映的是商户微信账户资金变动情况；
2. 当日账单在次日上午 9 点开始生成，建议商户在上午 10 点以后获取；
3. 资金账单中涉及金额的字段单位为“元”。

入参说明

返回值说明

content示例如下

• 第一行为表头

记账时间,微信支付业务单号,资金流水单号,业务名称,业务类型,收支类型,收支金额（元）,账户结余（元）,资金变更提交申请人,备注,业务凭证号

• 从第二行起，为资金流水数据，各参数以逗号分隔，参数前增加`符号，为标准键盘 1 左边键的字符，字段顺序与表头一致

• 倒数第二行为资金账单统计标题

资金流水总笔数,收入笔数,收入金额,支出笔数,支出金额

• 最后一行为统计数据

账单示例如下：

记账时间,微信支付业务单号,资金流水单号,业务名称,业务类型,收支类型,收支金额（元）,账户结余（元）,资金变更提交申请人,备注,业务凭证号

`2018-02-01 04:21:23,`50000305742018020103387128253,`1900009231201802015884652186,`退款,`退款,`支出,`0.02,`0.17,`system,`缺货,`REF4200000068201801293084726067

资金流水总笔数,收入笔数,收入金额,支出笔数,支出金额

`20.0,`17.0,`0.35,`3.0,`0.18

使用示例

exports.main = async function (event) {
  let res = await uniPayIns.downloadFundflow({
    billDate: '20200202',
  })
  return res
}

支付结果通知处理

uniPayIns.verifyPaymentNotify，用于在使用云函数 Url 化的云函数内检验并处理支付结果。

入参说明

只接收对应云函数的event作为参数

返回值说明

使用示例

exports.main = async function (event) {
  let res = await uniPayIns.verifyPaymentNotify(event)
  return res
}

退款结果通知

uniPayIns.verifyRefundNotify，用于在使用云函数 Url 化的云函数内检验并处理支付结果。

入参说明

只接收对应云函数的event作为参数

返回值说明

使用示例

exports.main = async function (event) {
  let res = await uniPayIns.verifyRefundNotify(event)
  return res
}