1. 接口规则

为了在保证支付安全的前提下，带给商户简单、一致且易用的开发体验，我们推出了全新的微信支付APIv3接口。该版本API的具体规则请参考APIv3接口规则。

2. 开发准备

2.1. 搭建和配置开发环境

为了帮助开发者调用开放接口，我们提供了JAVA、PHP、GO三种语言版本的开发库，封装了签名生成、签名验证、敏感信息加/解密、媒体文件上传等基础功能（更多语言版本的开发库将在近期陆续提供）。

测试步骤：

1、根据自身开发语言，选择对应的开发库并构建项目，具体配置请参考下面链接的详细说明：

wechatpay-java（推荐）、wechatpay-apache-httpclient，适用于Java开发者。
- 注：当前开发指引接口JAVA示例代码采用wechatpay-apache-httpclient版本。
wechatpay-php（推荐）、wechatpay-guzzle-middleware，适用于PHP开发者。
- 注：当前开发指引接口PHP示例代码采用wechatpay-guzzle-middleware版本。
wechatpay-go，适用于Go开发者。

更多资源可前往微信支付开发者社区搜索查看。

2、创建加载商户私钥、加载平台证书、初始化httpClient的通用方法。

JAVA

1@Before
2public void setup() throws IOException {
3    // 加载商户私钥（privateKey：私钥字符串）
4    PrivateKey merchantPrivateKey = PemUtil
5            .loadPrivateKey(new ByteArrayInputStream(privateKey.getBytes("utf-8")));
6 
7    // 加载平台证书（mchId：商户号,mchSerialNo：商户证书序列号,apiV3Key：V3密钥）
8    AutoUpdateCertificatesVerifier verifier = new AutoUpdateCertificatesVerifier(
9            new WechatPay2Credentials(mchId, new PrivateKeySigner(mchSerialNo, merchantPrivateKey)),apiV3Key.getBytes("utf-8"));
10 
11    // 初始化httpClient
12    httpClient = WechatPayHttpClientBuilder.create()
13            .withMerchant(mchId, mchSerialNo, merchantPrivateKey)
14            .withValidator(new WechatPay2Validator(verifier)).build();
15}
16 
17@After
18public void after() throws IOException {
19    httpClient.close();
20}

PHP

1use GuzzleHttp\Exception\RequestException;
2use WechatPay\GuzzleMiddleware\WechatPayMiddleware;
3use WechatPay\GuzzleMiddleware\Util\PemUtil;
4use GuzzleHttp\HandlerStack;
5 
6// 商户相关配置，
7$merchantId = '1000100'; // 商户号
8$merchantSerialNumber = 'XXXXXXXXXX'; // 商户API证书序列号
9$merchantPrivateKey = PemUtil::loadPrivateKey('./path/to/mch/private/key.pem'); // 商户私钥文件路径
10// 微信支付平台配置
11$wechatpayCertificate = PemUtil::loadCertificate('./path/to/wechatpay/cert.pem'); // 微信支付平台证书文件路径
12 
13// 构造一个WechatPayMiddleware
14$wechatpayMiddleware = WechatPayMiddleware::builder()
15    ->withMerchant($merchantId, $merchantSerialNumber, $merchantPrivateKey) // 传入商户相关配置
16    ->withWechatPay([ $wechatpayCertificate ]) // 可传入多个微信支付平台证书，参数类型为array
17    ->build();
18 
19// 将WechatPayMiddleware添加到Guzzle的HandlerStack中
20$stack = GuzzleHttp\HandlerStack::create();
21$stack->push($wechatpayMiddleware, 'wechatpay');
22 
23// 创建Guzzle HTTP Client时，将HandlerStack传入，接下来，正常使用Guzzle发起API请求，WechatPayMiddleware会自动地处理签名和验签
24$client = new GuzzleHttp\Client(['handler' => $stack]);

3、基于接口的示例代码，替换请求参数后可发起测试。

说明：

上面的开发库为微信支付官方开发库，其它没有审核或者控制下的第三方工具和库，微信支付不保证它们的安全性和可靠性。通过包管理工具引入SDK后，可根据下面每个接口的示例代码替换相关参数后进行快速测试。
开发者如果想详细了解签名生成、签名验证、敏感信息加/解密、媒体文件上传等常用方法的具体代码实现，可阅读下面的详细说明：

如想更详细的了解我们的接口规则，可查看我们的接口规则指引文档。

2.2. 接口体验

如果开发者使用过PostmanAPI的调试，建议在正式开发之前，使用 Postman签名脚本进行接口体验。

3. 商家转账业务接入说明

3.1. 业务流程图

3.2. 关键步骤说明

第一步：发起商家转账到零钱

1、调用接口前，开发者需要参考接入前准备确认已完成权限开通和产品配置，特别是关于API发起转账的相关配置一定要正确。

2、商户发起商家转账到零钱，先调用《发起批量转账》接口发起批次转账请求，受理成功将返回批次单号，此时并不代表转账成功。

3、当返回错误码为“SYSTEM_ERROR”时，请不要更换商家批次单号，一定要使用原商家批次单号及原参数重试，否则可能造成重复转账等资金风险。

4、受理成功后，在单据创建时间的3个自然日内使用同样批次单信息请求该接口，均返回应答码“200 OK”及对应的应答参数。

第二步：查询转账批次状态

1、使用API接口只支持查询最近30天内的转账批次单状态，30天之前的转账批次单请登录商户平台查询。

2、当发起商家转账到零钱请求受理成功之后，需等待10s-15min左右（批次内笔数越多所需等待时间越长）才可调用《通过微信批次单号查询批次单》、《通过商家批次单号查询批次单》接口来查询批次转账状态，若发起转账请求后立即查询，有可能查询到“转账批次单不存在”，请间隔几分钟再次尝试查询。

3、当查询到的批次单状态为：WAIT_PAY 时，表示「付款验密人」需要到「微信支付商户助手」输入安全密码验证，24小时内未完成验证，自动关闭批次单。

4、当查询到批次单状态为FINISHED(已完成),才可进行下一步，查询转账明细状态。

第三步：查询转账明细状态

当查询到批次单状态为FINISHED(已完成)，才可调用《通过微信明细单号查询明细单》、《通过商家明细单号查询明细单》接口进行转账明细查询。

第四步：申请下载电子回单(按需使用)

1、发起转账时传入了收款用户姓名，才支持申请电子回单。

2、支持受理2年内的转账批次电子回单和转账明细电子回单。

3、仅支持已完成状态且至少有一笔成功记录的批次获取转账批次电子回单(不满足条件返回 400 INVALID_REQUEST)；

4、仅支持转账已完成的明细单申请电子回单（不满足条件返回 400 PARAM_ERROR）；

5、详情参考申请转账账单电子回单接口、查询转账账单电子回单接口、申请转账明细账单电子回单、查询转账明细账单电子回单、下载电子回单。

进一步阅读

安全最佳实践

开发指引