前期准备
在使用 Postman 调试微信支付接口之前,你需要做好以下准备:
- 安装 Postman 客户端应用,或使用网页版;
- 成为 微信支付商户;
- 已申请 商户API私钥。
当你已经具备这三个条件,就可以进入微信支付接口调试之旅了~
脚本导入
方式一:通过 fork 方式
为了帮助商户开发者快速上手,微信官方将 调试微信支付接口的脚本 部署到了 Postman 云工作台 WeChat Pay Public Workspace。
在该工作台中,你只需要将名为 WeChatPay APIv3
的集合 fork 到自己的工作台,然后就可以在 Postman 上构造并发送微信支付 APIv3 请求。
具体操作如下图所示:
注: 需要确保你已经登录了 Postman 平台。
1、进入到 WeChat Pay Public Workspace 后选择 Create a fork
,进入到下一步。
2、填入标签 Fork Label
并选择目的工作台 Workspace
。一般情况下,导入个人工作台 My Workspace 即可,也可以选择导入其它工作台。点击 Fork Collection
完成导入,在你指定的 Workspace 中即可看到WeChatPay APIv3
。
3、WeChatPay APIv3
参考如下:
方式二:从本地导入
Note 不推荐本地导入脚本,不但麻烦而且容易出错,还不能同步上游的变更。
1、如果你有从本地导入的需求,首先,打开 WeChatPay APIv3 集合,展开选项后点击 Export
:
2、下载并保存 WeChatPay APIv3.postman_collection.json
文件至本地。然后,有两种方式本地导入 JSON 文件:
- Postman 界面左上角的
Import
按钮 - 菜单
File
>Import
发起导入
选择本地的 WeChatPay APIv3.postman_collection.json
,点击确认后,导入便完成了,操作如下图所示:
你会发现在工作台的 Collections 里新增了名为 WeChatPay APIv3
的一组请求。
配置 Environment
环境(Environment) 是一组变量 (Varibles) 的集合,脚本从环境中读取变量,用来计算请求的签名。
你可以从云工作台 WeChat Pay Public Workspace 中的 商户参数模版 中 fork 一个空环境到自己的工作台。
接下来,在你工作台的 Enviroments 中找到新建的环境,点击 Add a new varialbe
添加新的变量:
mchid
:必填,商户号;merchant_serial_no
:必填,商户 API 证书序列号;apiclient_key.pem
:必填,PEM 格式的商户 API 私钥;
Warning 为了安全,请仔细阅读安全注意事项。
一组常见配置如下图所示:
参数变量:
变量名 | 是否必填 | 描述 | 备注 |
---|---|---|---|
mchid | 是 | 商户号 | |
merchant_serial_no | 是 | 商户 API 证书的证书序列号 | |
apiclient_key.pem | 是 | PEM 格式的商户 API 私钥 | |
openid | 否 | 用户的 OpenID,测试请求中的 {{openid}} | |
appid | 否 | 公众账号或者小程序的 AppID | |
shangmi | 否 | 值为 true 时使用商密签名 | 默认值为空,即使用 RSA 签名 |
pubkey.pem | 国密签名时必填 | PEM 格式的商户 API 公钥 | 如果私钥 PEM 中包含公钥,该变量可不填 |
server_url | 否 | 服务器地址 | 默认设置为 https://api.mch.weixin.qq.com |
发送请求
现在回到工作台,进入WeChatPay APIv3
集合,选择你要发送的请求。
然后,填入请求参数,按照注释修改 Body 中的参数。
最后,选择你之前配置的 Environment,再点击地址栏右侧的Send
按钮,发送请求吧。
安全注意事项
商户 API 私钥是非常敏感的信息。使用此代码时,应记住以下几点:
- 将配置了私钥的工作台(workspace)的可见性(Visibility)设置为私有
Personal
或者Private
,不要设置为公开Public
。 - 私钥的变量类型设置为
secret
。变量值会以掩码的形式显示在屏幕上。 - 私钥的变量值设置在
Current Value
。Current Value
仅保存在本地 Session,不会被发送至 Postman 的服务器。 - 如果使用来自其他人的 Postman 脚本,请检查依赖库、变量和脚本,确保没有被修改,避免被植入不安全代码。
Note 有关 Postman 的安全机制,请参考 Postman Security。
常见问题
发送请求时遇到错误提示“Error: Too few bytes to parse DER.”或者“Too few bytes to read ASN.1 value.”
通常是环境 Environments 里配置的变量 merchantPrivateKey
填写有误导致的。脚本接收的私钥,以 -----BEGIN PRIVATEKEY-----
开始,以 -----END PRIVATE KEY-----
结束的一串字符串。
为什么我发送请求很慢?
如果你使用的网页版 Postman,请使用桌面版 Postman app。因为浏览器中跨域资源共享(CORS)的限制,网页版发送请求是由 Postman 后台中转的。
使用中文软件更便捷去调试
如果你的英语比较一般,想要使用中文版本的接口去调试,可以看看:如何使用 Apifox 调试微信支付接口
知识扩展:
- Postman 传递 Date 类型参数
- 如何在 Postman 中进行 HTTPS 请求