<commit_before>## 简介

`unipay`为`uniCloud`开发者提供了简单、易用、统一的支付能力封装。让开发者无需研究支付宝、微信等支付平台的后端开发、无需为它们编写不同代码，拿来即用，屏蔽差异。

`uni-app`前端已经封装的全端支付 api `uni.requestPayment`，现在服务端也封装好了`unipay for uniCloud`，从此开发者可以极快的完成前后一体的支付业务。

目前已封装 App 端（微信支付和支付宝支付）、微信小程序、支付宝小程序的支付能力。

`unipay`是开源 sdk，可放心使用。本插件还包含示例工程，配置自己在微信和支付宝申请的相关配置后即可运行。

为了更好的体验支付流程可以在插件市场导入`unipay`的示例项目快速体验，[插件市场 unipay](https://ext.dcloud.net.cn/plugin?id=1835)

**须知**

- unipay 对入参和返回值均做了驼峰转化，开发者在对照微信支付或者支付宝支付对应的文档时需要注意。
- 特殊参数`appId`、`mchId`需注意大小写
- 所有金额被统一为以分为单位
- 为避免无关参数干扰此文档仅列举必填参数，其余参数请参照[微信支付-小程序](https://pay.weixin.qq.com/wiki/doc/api/wxa/wxa_api.php?chapter=9_1)、[微信支付-App](https://pay.weixin.qq.com/wiki/doc/api/app/app.php?chapter=9_1)、[支付宝支付-小程序](https://opendocs.alipay.com/apis/api_1/alipay.trade.create)、[支付宝支付-App](https://opendocs.alipay.com/apis/api_1/alipay.trade.app.pay)
- 微信支付沙箱环境不支持小程序支付，另外此沙箱环境只可以跑微信提供的测试用例不可以随意测试
- 无论是微信还是支付宝，沙箱环境都不确保稳定，如果使用沙箱的过程中遇到疑难问题建议切换成正式环境测试

**问题排查指引**

- [支付宝支付蚂蚁技术支持](https://openclub.alipay.com/club/history/read/7695)

## 引入 unipay

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

```js
// 插件市场导入
const unipay = require('unipay')

// npm安装
const unipay = require('@dcloudio/unipay')
```

**注意**

- 插件市场导入的用法请参考[云函数公用模块](https://uniapp.dcloud.net.cn/uniCloud/cf-common)

## 初始化

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

### 微信支付

**入参说明**

|   参数名   |  类型   |  必填  |                        默认值                        |                  说明                  |
| :--------: | :-----: | :----: | :--------------------------------------------------: | :------------------------------------: |
|   appId    | String  |   是   |                          -                           |     当前应用在对应支付平台的 appId     |
|   mchId    | String  |   是   |                          -                           |                 商户号                 |
|    key     | String  |   是   |                          -                           |            支付商户 md5 key            |
|    pfx     | String  | Buffer |                   使用退款功能必填                   |       微信支付商户 API 证书，主要用于退款 |
|  timeout   | Number  |   否   |                         5000                         |        请求超时时间，单位：毫秒        |
|  signType  | String  |   否   |                         MD5                          |                签名类型                |
|  sandbox   | Boolean |   否   |                        false                         |            是否启用沙箱环境            |
| clientType | String  |   否   | 默认自动获取客户端类型，同 `context` 内的 `PLATFORM` | 客户端类型，主要用于返回客户端支付参数 |

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

### 支付宝支付

**入参说明**

|     参数名						|  类型		| 必填|                        默认值												|                  说明									|
| :-------------:				| :-----:	| :--:| :--------------------------------------------------:| :------------------------------------:|
|      appId						| String	|  是	|                          -													|     当前应用在对应支付平台的 appId		|
|   mchId    | String  |   是   |                          -                           |                 商户号                 |
|   privateKey					| String	|  是	|                          -													|             应用私钥字符串						|
| alipayPublicKey				| String	|  否	|                          -													|          支付宝公钥，验签使用					|
|     keyType						| String	|  否	|                        PKCS8												|           应用私钥字符串类型					|
|     timeout						| Number	|  否	|                         5000												|        请求超时时间，单位：毫秒				|
|    signType						| String	|  否	|                         RSA2												|                签名类型								|
|     sandbox						| Boolean	|  否	|                        false												|            是否启用沙箱环境						|
|   clientType					| String	|  否	| 默认自动获取客户端类型，同 `context` 内的 `PLATFORM`| 客户端类型，主要用于返回客户端支付参数|
|   alipayRootCertPath	| String	|  否	| -																										| `1.0.6+`，支付宝根证书文件路径				|
|   appCertPath					| String	|  否	| -																										| `1.0.6+`，应用公钥证书文件路径				|
|   alipayPublicCertPath| String	|  否	| -																										| `1.0.6+`，支付宝公钥证书文件路径			|

```js
const unipayIns = unipay.initAlipay({
  appId: 'your appId',
  mchId: 'your mchId',
  privateKey: 'your privateKey',
  // 如果不使用证书（普通公钥模式）需要alipayPublicKey
  alipayPublicKey: 'you alipayPublicKey', // 使用支付时需传递此值做返回结果验签
  // 如果使用证书需要传alipayRootCertPath、appCertPath、alipayPublicCertPath
  alipayRootCertPath: path.join(__dirname,'../fixtures/alipayRootCert.crt'),
  appCertPath: path.join(__dirname,'../fixtures/appCertPublicKey.crt'),
  alipayPublicCertPath: path.join(__dirname,'../fixtures/alipayCertPublicKey_RSA2.crt'),
})
```

## Api 列表

### 获取支付参数

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

**入参说明**

|   参数名	|  类型	|                必填														| 默认值|                                    说明																																						|         支持平台				|
| :--------:| :----:| :--------------------------------:						| :----:| :------------------------------------------------------------------------:																				| :----------------------:|
|   openid	| String| 支付宝小程序、微信小程序必填，App端支付不需要	|   -		|                  通过对应 [uni-account](https://ext.dcloud.net.cn/plugin?id=1834) 的 code2Session 获取						| 支付宝小程序、微信小程序|
|  subject	| String| 支付宝支付必填，微信支付时忽略此项						|   -		|                                  订单标题																																					|        支付宝支付				|
|    body		| String|            微信支付必填												|   -		|                                  商品描述																																					|         微信支付				|<commit_msg>docs: uniPay keyType tips<commit_after>## 简介

`unipay`为`uniCloud`开发者提供了简单、易用、统一的支付能力封装。让开发者无需研究支付宝、微信等支付平台的后端开发、无需为它们编写不同代码，拿来即用，屏蔽差异。

`uni-app`前端已经封装的全端支付 api `uni.requestPayment`，现在服务端也封装好了`unipay for uniCloud`，从此开发者可以极快的完成前后一体的支付业务。

目前已封装 App 端（微信支付和支付宝支付）、微信小程序、支付宝小程序的支付能力。

`unipay`是开源 sdk，可放心使用。本插件还包含示例工程，配置自己在微信和支付宝申请的相关配置后即可运行。

为了更好的体验支付流程可以在插件市场导入`unipay`的示例项目快速体验，[插件市场 unipay](https://ext.dcloud.net.cn/plugin?id=1835)

**须知**

- unipay 对入参和返回值均做了驼峰转化，开发者在对照微信支付或者支付宝支付对应的文档时需要注意。
- 特殊参数`appId`、`mchId`需注意大小写
- 所有金额被统一为以分为单位
- 为避免无关参数干扰此文档仅列举必填参数，其余参数请参照[微信支付-小程序](https://pay.weixin.qq.com/wiki/doc/api/wxa/wxa_api.php?chapter=9_1)、[微信支付-App](https://pay.weixin.qq.com/wiki/doc/api/app/app.php?chapter=9_1)、[支付宝支付-小程序](https://opendocs.alipay.com/apis/api_1/alipay.trade.create)、[支付宝支付-App](https://opendocs.alipay.com/apis/api_1/alipay.trade.app.pay)
- 微信支付沙箱环境不支持小程序支付，另外此沙箱环境只可以跑微信提供的测试用例不可以随意测试
- 无论是微信还是支付宝，沙箱环境都不确保稳定，如果使用沙箱的过程中遇到疑难问题建议切换成正式环境测试

**问题排查指引**

- [支付宝支付蚂蚁技术支持](https://openclub.alipay.com/club/history/read/7695)

## 引入 unipay

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

```js
// 插件市场导入
const unipay = require('unipay')

// npm安装
const unipay = require('@dcloudio/unipay')
```

**注意**

- 插件市场导入的用法请参考[云函数公用模块](https://uniapp.dcloud.net.cn/uniCloud/cf-common)

## 初始化

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

### 微信支付

**入参说明**

|   参数名   |  类型   |  必填  |                        默认值                        |                  说明                  |
| :--------: | :-----: | :----: | :--------------------------------------------------: | :------------------------------------: |
|   appId    | String  |   是   |                          -                           |     当前应用在对应支付平台的 appId     |
|   mchId    | String  |   是   |                          -                           |                 商户号                 |
|    key     | String  |   是   |                          -                           |            支付商户 md5 key            |
|    pfx     | String  | Buffer |                   使用退款功能必填                   |       微信支付商户 API 证书，主要用于退款 |
|  timeout   | Number  |   否   |                         5000                         |        请求超时时间，单位：毫秒        |
|  signType  | String  |   否   |                         MD5                          |                签名类型                |
|  sandbox   | Boolean |   否   |                        false                         |            是否启用沙箱环境            |
| clientType | String  |   否   | 默认自动获取客户端类型，同 `context` 内的 `PLATFORM` | 客户端类型，主要用于返回客户端支付参数 |

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

### 支付宝支付

**入参说明**

|     参数名						|  类型		| 必填|                        默认值												|                  说明									|
| :-------------:				| :-----:	| :--:| :--------------------------------------------------:| :------------------------------------:|
|      appId						| String	|  是	|                          -													|     当前应用在对应支付平台的 appId		|
|   mchId    | String  |   是   |                          -                           |                 商户号                 |
|   privateKey					| String	|  是	|                          -													|             应用私钥字符串						|
| alipayPublicKey				| String	|  否	|                          -													|          支付宝公钥，验签使用					|
|     keyType						| String	|  否	|                        PKCS8												|           应用私钥字符串类型					|
|     timeout						| Number	|  否	|                         5000												|        请求超时时间，单位：毫秒				|
|    signType						| String	|  否	|                         RSA2												|                签名类型								|
|     sandbox						| Boolean	|  否	|                        false												|            是否启用沙箱环境						|
|   clientType					| String	|  否	| 默认自动获取客户端类型，同 `context` 内的 `PLATFORM`| 客户端类型，主要用于返回客户端支付参数|
|   alipayRootCertPath	| String	|  否	| -																										| `1.0.6+`，支付宝根证书文件路径				|
|   appCertPath					| String	|  否	| -																										| `1.0.6+`，应用公钥证书文件路径				|
|   alipayPublicCertPath| String	|  否	| -																										| `1.0.6+`，支付宝公钥证书文件路径			|

```js
const unipayIns = unipay.initAlipay({
  appId: 'your appId',
  mchId: 'your mchId',
  privateKey: 'your privateKey',
  // 如果不使用证书（普通公钥模式）需要alipayPublicKey
  alipayPublicKey: 'you alipayPublicKey', // 使用支付时需传递此值做返回结果验签
  // 如果使用证书需要传alipayRootCertPath、appCertPath、alipayPublicCertPath
  alipayRootCertPath: path.join(__dirname,'../fixtures/alipayRootCert.crt'),
  appCertPath: path.join(__dirname,'../fixtures/appCertPublicKey.crt'),
  alipayPublicCertPath: path.join(__dirname,'../fixtures/alipayCertPublicKey_RSA2.crt'),
})
```

**常见问题**

- 支付宝支付时遇到`error:0D0680A8:asn1 encoding routines:ASN1_CHECK_TLEN:wrong tag`类似的错误时请确认一下自己的私钥格式，如果不是PKCS8需要在初始化时传入keyType参数，值为对应的私钥格式

## Api 列表

### 获取支付参数

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

**入参说明**

|   参数名	|  类型	|                必填														| 默认值|                                    说明																																						|         支持平台				|
| :--------:| :----:| :--------------------------------:						| :----:| :------------------------------------------------------------------------:																				| :----------------------:|
|   openid	| String| 支付宝小程序、微信小程序必填，App端支付不需要	|   -		|                  通过对应 [uni-account](https://ext.dcloud.net.cn/plugin?id=1834) 的 code2Session 获取						| 支付宝小程序、微信小程序|
|  subject	| String| 支付宝支付必填，微信支付时忽略此项						|   -		|                                  订单标题																																					|        支付宝支付				|
|    body		| String|            微信支付必填												|   -		|                                  商品描述																																					|         微信支付				|
{'fraction_non_alphanumeric': 0.17321599721181494, 'fraction_numerical': 0.008277424414045482, 'mean_word_length': 1.149035761093428, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 16, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 65, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1424053', 'n_tokens_mistral': 5579, 'n_tokens_neox': 5781, 'n_words': 476}