Menu
User login
产品能力API字典接口规则接入规范常见问题名词表更新日志

开发指引

更新时间：2025.03.24

1. 接口规则

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

2. 开发环境搭建

为了帮助开发者调用开放接口，我们提供了Java、PHP、GO语言版本的开发库，封装了签名生成、签名验证、敏感信息加/解密、媒体文件上传等基础功能

JAVA

2.1.1. 使用条件

  • WechatPay merchant account

  • Java 1.8 or later

  • Maven or Gradle;

  • 0.4.6 or later version of the Java httpClient SDK

2.1.2. 安装

Gradle：在你的 build.gradle 文件中加入如下的依赖

1implementation 'com.github.wechatpay-apiv3:wechatpay-apache-httpclient:0.4.7'

Maven：在 pom.xml 文件中加入以下依赖

1<dependency>
2<groupId>com.github.wechatpay-apiv3</groupId>
3<artifactId>wechatpay-apache-httpclient</artifactId>
4<version>0.4.7</version>
5</dependency>

2.1.3. 初始化

用WechatPayHttpClientBuilder初始化创建一个httpClient，httpClient将被用于发送请求调用微信支付接口。 用CertificatesManager初始化一个verifier实例，用于验证签名。

1    private CloseableHttpClient httpClient;
2    private CertificatesManager certificatesManager;
3    private Verifier verifier;
4
5    @Before
6    //initialize verifier and build httpClient
7    public void setup() throws GeneralSecurityException, IOException, HttpCodeException, NotFoundException {
8
9        PrivateKey merchantPrivateKey = PemUtil.loadPrivateKey(privateKey);
10        certificatesManager = CertificatesManager.getInstance();
11        certificatesManager.putMerchant(merchantId, new WechatPay2Credentials(merchantId,
12                        new PrivateKeySigner(merchantSerialNumber, merchantPrivateKey)),
13                apiV3Key.getBytes(StandardCharsets.UTF_8));
14        verifier = certificatesManager.getVerifier(merchantId);
15        WechatPayHttpClientBuilder builder = WechatPayHttpClientBuilder.create()
16                .withMerchant(merchantId, merchantSerialNumber, merchantPrivateKey)
17                .withValidator(new WechatPay2Validator(verifier));
18        httpClient = builder.build();
19    }

2.1.4. 通用功能

敏感信息加密

1    @Test
2    public void encryptedTest() throws IllegalBlockSizeException {
3        String text = "helloWorld";
4        String transformation = "RSA/ECB/PKCS1Padding";
5        String encryptedText = RsaCryptoUtil.encrypt(text, verifier.getValidCertificate(), transformation);
6        System.out.println(encryptedText);
7    }

敏感信息解密

1    @Test
2    public void decryptedTest() throws BadPaddingException {
3        String encryptedText = OBTgun4jiN13n3nmSg8v0MNDMy3mbs380yq4GrgO8vwCqXnvrWxwo3jUCNY2UY7MIOtv/SD8ke64MxcSB0hn5EzKv1LOLprI3NvvmNLS4C3SBulxpZG62RYp1+8FgwAI4M//icXvjtZWVH4KVDg==";
4        String transformation = "RSA/ECB/PKCS1Padding";
5        String decryptedText = RsaCryptoUtil.decrypt(encryptedText, PemUtil.loadPrivateKey(privateKey), transformation);
6        assert("helloWorld".equals(decryptedText));
7    }

Golang

2.2.1. 使用条件

  • WechatPay merchant account

  • GO SDK 0.2.13 or later version

2.2.2. 安装

1. 使用 Go Modules 管理你的项目

如果你的项目还不是使用 Go Modules 做依赖管理，在项目根目录下执行：

go mod init

2. 无需 clone 仓库中的代码，直接在项目目录中执行：

来添加依赖，完成 go.mod 修改与 SDK 下载

2.2.3. 初始化

初始化Client并向Client中加载商户号，私钥，API V3 key，商户证书和序列号， 用于之后发送接口请求。

1import (
2   "context"
3   "crypto/rand"
4   "crypto/rsa"
5   "crypto/x509"
6   "encoding/base64"
7   "fmt"
8   "github.com/wechatpay-apiv3/wechatpay-go/core"
9   "github.com/wechatpay-apiv3/wechatpay-go/core/option"
10   "github.com/wechatpay-apiv3/wechatpay-go/utils"
11   "log"
12   "net/http"
13)
14
15var (
16   mchID                      = ""                  // merchant id
17   mchCertificateSerialNumber = "" // merchant certificate serial number
18   mchAPIv3Key                = ""                  // merchant api v3 key
19   header                     = make(http.Header)
20   ctx                        = context.Background()
21   cert                       *x509.Certificate
22   mchPrivateKey              *rsa.PrivateKey
23   client                     *core.Client
24   err                        error
25)
26
27func setup() {
28   //Load platform certificate
29   cert, err = utils.LoadCertificateWithPath("Path/To/Platform/Cert")
30   if err != nil {
31      log.Fatal(err)
32   }
33   // Load private key
34   mchPrivateKey, err = utils.LoadPrivateKeyWithPath("Path/To/Private/Key")
35   if err != nil {
36      log.Fatal("load merchant private key error")
37   }
38   // Initialize client which is capable to update platform certificate periodically
39   opts := []core.ClientOption{
40      option.WithWechatPayAutoAuthCipher(mchID, mchCertificateSerialNumber, mchPrivateKey, mchAPIv3Key),
41   }
42   client, err = core.NewClient(ctx, opts...)
43   if err != nil {
44      log.Fatalf("new wechat pay client err:%s", err)
45   }
46}

2.2.4. 通用功能

敏感信息加密

1
2func Encryption(t *testing.T) {
3	var testRSACryptoUtilMchCertificateStr = `-----BEGIN CERTIFICATE-----
4	-----END CERTIFICATE-----`
5	testRSACryptoUtilCertificate, _ = LoadCertificate(testRSACryptoUtilMchCertificateStr)
6   const message = "hello world"
7   
8   // 使用OAEP padding方式对证书加密
9   ciphertext, _ := EncryptOAEPWithCertificate(message, testRSACryptoUtilCertificate)
10   
11   // 使用PKCS1 padding对证书加密
12   ciphertext, _ := EncryptPKCS1v15WithCertificate(message, testRSACryptoUtilCertificate)
13}
14

敏感信息解密

1func TestDecryption(t *testing.T) {
2	var testRSACryptoUtilPrivateKeyStr = `-----BEGIN PRIVATE KEY-----
3-----END PRIVATE KEY-----`
4	testRSACryptoUtilPrivateKey, _ = LoadPrivateKey(testingKey(testRSACryptoUtilPrivateKeyStr))
5	const ciphertext = ""
6
7	// 使用PKCS1 padding进行私钥解密
8	decryptMessage, _ := DecryptPKCS1v15(ciphertext, testRSACryptoUtilPrivateKey)
9
10	// 使用OAEP padding方式私钥解密
11	decryptMessage, _ := DecryptOAEP(ciphertext, testRSACryptoUtilPrivateKey)
12}

PHP

2.3.1. 使用条件

  • Guzzle 7.0，PHP >= 7.2.5

  • Guzzle 6.5，PHP >= 7.1.2

  • 项目已支持 PHP 8。

2.3.2. 安装

推荐使用 PHP 包管理工具 Composer 安装 SDK：

composer require wechatpay/wechatpay

2.3.3. 初始化

初始化Client并向Client中加载商户号，私钥，API V3 key，商户证书和序列号， 用于之后发送接口请求。

1
2require_once('vendor/autoload.php');
3
4use WeChatPay\Builder;
5use WeChatPay\Crypto\Rsa;
6use WeChatPay\Util\PemUtil;
7
8$merchantId = '190000****';
9$merchantPrivateKeyFilePath = 'file:///path/to/merchant/apiclient_key.pem';
10$merchantPrivateKeyInstance = Rsa::from($merchantPrivateKeyFilePath, Rsa::KEY_TYPE_PRIVATE);
11$merchantCertificateSerial = '3775B6A45ACD588826D15E583A95F5DD********';
12$platformCertificateFilePath = 'file:///path/to/wechatpay/cert.pem';
13$platformPublicKeyInstance = Rsa::from($platformCertificateFilePath, Rsa::KEY_TYPE_PUBLIC);
14$platformCertificateSerial = PemUtil::parseCertificateSerialNo($platformCertificateFilePath);
15
16// init a API V3 instance
17$instance = Builder::factory([
18    'mchid'      => $merchantId,
19    'serial'     => $merchantCertificateSerial,
20    'privateKey' => $merchantPrivateKeyInstance,
21    'certs'      => [
22        $platformCertificateSerial => $platformPublicKeyInstance,
23    ],
24]); 
25

2.3.4. 通用功能

敏感信息加密

1    $encryptor = static function(string $msg) use ($platformPublicKeyInstance): string {
2        return Rsa::encrypt($msg, $platformPublicKeyInstance, OPENSSL_PKCS1_PADDING);
3    };
4	$encryptedMsg =  $encryptor('HelloWorld');

敏感信息解密

1    $decryptor = static function(string $msg) use ($merchantPrivateKeyInstance): string {
2        return Rsa::decrypt($msg, $merchantPrivateKeyInstance, OPENSSL_PKCS1_PADDING);
3    };
4	$decryptedMsg =  $decryptor('ciphertext');

 

3. 业务时序图

3.1. 业务时序图

3.2. API接入示例

文档展示了如何使用微信支付服务端 SDK 快速接入扫码支付产品，完成与微信支付对接的部分。

注意

  • 文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。

  • 以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。

3.2.1 下单

步骤说明：通过本接口提交微信支付H5支付订单，获取微信支付跳转链接mweb_url。

代码示例 - JAVA：

1 @Test
2    //Call Unified Order API
3    public void unifiedOrderTest() throws IOException {
4      String unifiedOrderBody = String.join("\n" ,
5                		"{" ,
6                        "'sp_appid': 'wx2421b1c4370ec43b'," ,
7                        "'sp_mchid': '10000100'," ,
8                        "'sub_mchid': '20000100'," ,
9                        "'out_trade_no': '20150806125346'," ,
10                        "'merchant_category_code': '1011'," ,
11                        "'notify_url': 'https://wxpay.wxutil.com/pub_v2/pay/notify.v2.php'," ,
12                        "'trade_type': 'MWEB'," ,
13                        "'amount': {" ,
14                        "'total': 10000," ,
15                        "'currency': 'HKD'" ,
16                        "}," ,
17                        "'attach': 'Payment test'," ,
18                        "'description': 'In-APP Pay test'," ,
19                        "'goods_tag': '," ,
20                        "'detail': {" ,
21                        "'cost_price': 10000," ,
22                        "'receipt_id': '1234'," ,
23                        "'goods_detail': [{" ,
24                        "'goods_id': 'iphone6s_16G'," ,
25                        "'wxpay_goods_id': '1001'," ,
26                        "'goods_name': 'iPhone6s 16G'," ,
27                        "'quantity': 1," ,
28                        "'price': 528800" ,
29                        "}]" ,
30                        "}," ,
31                        "'scene_info': {" ,
32                        "'payer_client_ip': '14.23.150.211'," ,
33                        "'device_ip': '59.37.125.32'," ,
34                        "'device_id': '013467007045764'," ,
35                        "'operator_id': 'P001'," ,
36                        "'store_info': {" ,
37                        "'id': 'SZTX001'" ,
38                        "}" ,
39                        "}" ,
40                        "}").replace("'","\"");
41        HttpPost httpPost = new HttpPost("https://apihk.mch.weixin.qq.com/v3/global/transactions/mweb");
42        httpPost.addHeader("Accept", "application/json");
43        httpPost.addHeader("Content-type", "application/json; charset=utf-8");
44        httpPost.setEntity(new StringEntity(unifiedOrderBody));
45        CloseableHttpResponse response = httpClient.execute(httpPost);
46        //Process the response
47    }

示例代码 - GO：

1//Call unified order API
2func unifiedOrder() {
3   orderRequestBody := `{
4	"sp_appid": "wx2421b1c4370ec43b",
5	"sp_mchid": "10000100",
6	"sub_mchid": "20000100",
7	"out_trade_no": "20150806125346",
8	"merchant_category_code": "1011",
9	"notify_url": "https://wxpay.wxutil.com/pub_v2/pay/notify.v2.php",
10	"trade_type": "MWEB",
11	"amount": {
12		"total": 10000,
13		"currency": "HKD"
14	},
15	"attach": "Payment test",
16	"description": "In-APP Pay test",
17	"goods_tag": "",
18	"detail": {
19		"cost_price": 10000,
20		"receipt_id": "1234",
21		"goods_detail": [{
22			"goods_id": "iphone6s_16G",
23			"wxpay_goods_id": "1001",
24			"goods_name": "iPhone6s 16G",
25			"quantity": 1,
26			"price": 528800
27		}]
28	},
29	"scene_info": {
30		"payer_client_ip": "14.23.150.211",
31		"device_ip": "59.37.125.32",
32		"device_id": "013467007045764",
33		"operator_id": "P001",
34		"store_info": {
35			"id": "SZTX001"
36		}
37	}
38}`
39   result, err := client.Post(ctx, "https://apihk.mch.weixin.qq.com/v3/global/transactions/mweb", orderRequestBody)
40   if err != nil {
41      // Process error
42   }
43   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
44}

示例代码 - PHP：

1// Call Unified Order API
2public function unifiedOrder($instance){
3    try {
4        $resp = $instance
5            ->chain('v3/global/transactions/mweb')
6            ->post(['json' => [
7                'sp_appid'     => 'wxdace645e0bc2c424',
8                'sp_mchid'     => '10000100',
9                'sub_mchid'    => '20000100',
10                'out_trade_no' => 'YX201710140020Z',
11                'merchant_category_code' => '4111',
12                'notify_url'   => 'https://weixin.qq.com/',
13                'trade_type'   => 'MWEB',
14                'amount'       => [
15                    'total'    => 1,
16                    'currency' => 'USD'
17                ],	
18				'scene_info'   => [
19					'payer_client_ip' => '14.23.150.211'
20				],
21                'attach'  => 'mini-program payment test',
22                'description'  => 'Image形象店-深圳腾大-QQ公仔',
23                'goods_tag'  => '001'
24            ]]);
25
26        echo $resp->getStatusCode(), PHP_EOL;
27        echo $resp->getBody(), PHP_EOL;
28    } catch (Exception $e) {
29        // EXception handling
30        echo $e->getMessage(), PHP_EOL;
31        if ($e instanceof \GuzzleHttp\Exception\RequestException && $e->hasResponse()) {
32            $r = $e->getResponse();
33            echo $r->getStatusCode() . ' ' . $r->getReasonPhrase(), PHP_EOL;
34            echo $r->getBody(), PHP_EOL, PHP_EOL, PHP_EOL;
35        }
36        echo $e->getTraceAsString(), PHP_EOL;
37    }
38}

重要参数：

out_trade_no: 商户系统内部订单号

notify_url: 接受异步支付结果回调通知的地址，通知url必须为外网可访问的url，不能携带参数。请使用https协议链接

其他重要参数请前往H5支付下单API文档页面参考。

3.2.2 查询订单

步骤说明：商户在用户下单一定时间后，需主动进行查单以确认订单状态。

代码示例 - JAVA：

1
2    @Test
3    //Call query order API
4    public void queryOrderTest() throws IOException {
5        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/transactions/id/" +
6                "4200123456789000?sub_mchid=100012321&sp_mchid=1900000000");
7        httpGet.addHeader("Accept", "application/json");
8        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
9        CloseableHttpResponse response = httpClient.execute(httpGet);
10        //Process the response 
11    }
12

示例代码 - GO：

1
2//Call query order API
3func queryOrder() {
4   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/transactions/id/4200000000000000?sub_mchid=100012321&sp_mchid=1900000000")
5   if err != nil {
6      // Process error
7   }
8   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
9}

示例代码 - PHP：

1
2// Call query order API
3public function queryOrder($instance)
4{
5    try {
6        $resp = $instance
7            ->v3->global->transactions->outTradeNo->_out_trade_no_
8            ->get([
9                    'query' => [
10                'sp_mchid'     => '1900000000',
11                'sub_mchid'    => '100012321',
12                    ],
13                    'out_trade_no' => 'YX0001'
14                ]
15            );
16
17        echo $resp->getStatusCode(), PHP_EOL;
18        echo $resp->getBody(), PHP_EOL;
19    } catch (Exception $e) {
20        // Exception handling
21	}
22}

重要参数：

id： 微信支付订单号

out_trade_no：商户内部订单号

可以用上述任一订单号进行查询。其他重要参数请前往查询订单API文档页面参考。

3.2.3 申请退款

步骤说明：支付完成支付状态为SUCCESS后，可以调用该接口提交退款请求。

代码示例 - JAVA：

1
2    @Test
3    //Call Refund API
4    public void refundTest() throws IOException {
5		String refundBody = String.join("\n" ,
6                		"{" ,
7                        "'sp_appid': 'wx2421b1c4370ec43b', " ,
8                        "'sp_mchid': '10000100'," ,
9                        "'sub_mchid': '20000100'," ,
10                        "'transaction_id': '1008450740201411110005820873'," ,
11                        "'out_refund_no': 'R20150806125346'," ,
12                        "    'amount' : {" ,
13                        "        'refund': 5," ,
14                        "        'total':10," ,
15                        "         'currency':'HKD'" ,
16                        "    }," ,
17                        "    'reason': 'The item has been sold out.'," ,
18                        "    'source': 'REFUND_SOURCE_UNSETTLED_FUNDS'" ,
19                        "}").replace("'","\"");
20        HttpPost httpPost = new HttpPost("https://apihk.mch.weixin.qq.com/v3/global/refunds");
21        httpPost.addHeader("Accept", "application/json");
22        httpPost.addHeader("Content-type", "application/json; charset=utf-8");
23        httpPost.setEntity(new StringEntity(refundBody));
24        CloseableHttpResponse response = httpClient.execute(httpPost);
25        //Process the response 
26    }
27

示例代码 - GO：

1
2func refund() {
3   refundRequestBody := `{
4    "sp_appid": "wx2421b1c4370ec43b",
5    "sp_mchid": "10000100",
6    "sub_mchid": "20000100",
7    "transaction_id": "1008450740201411110005820873",
8    "out_refund_no": "R20150806125346",
9    "amount" : {
10        "refund": 50,
11        "total":100,
12         "currency":"HKD"
13    },
14    "reason": "The item has been sold out",
15    "source": "REFUND_SOURCE_UNSETTLED_FUNDS"
16}`
17   result, err := client.Post(ctx, "https://apihk.mch.weixin.qq.com/v3/global/refunds", refundRequestBody)
18   if err != nil {
19      // Process error
20   }
21   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
22}

示例代码 - PHP：

1
2// Call Refund API
3public function refundOrder($instance){
4    try {
5        $resp = $instance
6            ->chain('v3/global/refunds')
7            ->post(['json' => [
8                'sp_appid'     => 'wxdace12300000000',
9                'sp_mchid'     => '1900000000',
10                'sub_mchid'    => '100012321',
11                'out_trade_no' => 'YX0001',
12                "out_refund_no"=> "REFUNDYX0001",
13                'amount'       => [
14                    'refund'   => 1,
15                    'total'    => 1,
16                    'currency' => 'USD'
17                ]
18            ]]);
19        echo $resp->getStatusCode(), PHP_EOL;
20        echo $resp->getBody(), PHP_EOL;
21    } catch (Exception $e) {
22        // Exception handling
23    }
24}

重要参数：

out_trade_no: 商户内部订单号

transaction_id: 微信订单号

out_refund_no: 商户内部退款单号，应与订单号一一对应

notify_url: 退款结果接收地址

其他重要参数请前往申请退款API文档页面参考。

3.2.4 查询单笔退款

步骤说明：提交退款申请后，通过调用该接口查询退款状态。

代码示例 - JAVA：

1
2    @Test
3    //Call Query Refund API
4    public void querySingleRefundTest() throws IOException {
5        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/refunds/out-refund-no/RYX001?sub_mchid=100012321&sp_mchid=1900000000");
6        httpGet.addHeader("Accept", "application/json");
7        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
8        CloseableHttpResponse response = httpClient.execute(httpGet);
9        //Process the response 
10    }
11

示例代码 - GO：

1
2//Query single refund API
3func querySingleRefund() {
4   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/refunds/out-refund-no/REFUNDYX001?sub_mchid=100012321&sp_mchid=1900000000")
5   if err != nil {
6      // Process error
7   }
8   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
9}

示例代码 - PHP：

1
2// Call Query Refund API
3public function queryRefund($instance){
4    try {
5        $resp = $instance
6            ->v3->global->refunds->outRefundNo->_out_refund_no_
7            ->get([
8                'query' => [
9                    'sp_mchid' => '1900000000',
10                    'sub_mchid'=> '100012321'
11                ],
12                'out_refund_no' => 'REFUNDYX0001'
13            ]);
14
15        echo $resp->getStatusCode(), PHP_EOL;
16        echo $resp->getBody(), PHP_EOL;
17    } catch (Exception $e) {
18        // Exception handling
19    }
20}

重要参数：

out_trade_no: 商户内部订单号

refund_id：微信支付退款单号

其他重要参数请前往查询单笔退款API文档页面参考。

3.2.5 查询所有退款

步骤说明：提交退款申请后，通过调用该接口查询一笔订单下对应的全部退款信息。

代码示例 - JAVA：

1
2    @Test
3    //Call Query All Refund API
4    public void queryAllRefundTest() throws IOException {
5        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/refunds" +
6                "?out_trade_no=YX202111100020&count=10&offset=0&sp_mchid=1900000000&sub_mchid=100012321");
7        httpGet.addHeader("Accept", "application/json");
8        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
9        CloseableHttpResponse response = httpClient.execute(httpGet);
10        //Process the response 
11    }
12

示例代码 - GO：

1
2//Query all refund API
3func queryAllRefund() {
4   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/refunds/out-refund-no/out_trade_no=YX001&count=10&offset=0&sp_mchid=1900000000&sub_mchid=100012321")
5   if err != nil {
6      // Process error
7   }
8   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
9}

示例代码 - PHP：

1
2// Call Query All Refund API
3public function queryAllRefund($instance){
4    try {
5        $resp = $instance
6            ->v3->global->refunds
7            ->get([
8                'query' => [
9                    'out_trade_no' => 'YX001',
10                    'count' => 10,
11                    'offset' => 0,
12                    'sp_mchid' => '1900000000',
13                    'sub_mchid'=> '100012321'
14                ]
15            ]);
16
17        echo $resp->getStatusCode(), PHP_EOL;
18        echo $resp->getBody(), PHP_EOL;
19    } catch (Exception $e) {
20        // Exception handling
21    }
22}

重要参数：

out_trade_no: 商户内部订单号

transaction_id: 微信订单号

offset: 分页起始位置

count: 单页返回的记录数，最大20条记录.

其他重要参数请前往查询所有退款API文档页面参考。

3.2.6 下载对账单

步骤说明：商户每天可以通过调用该接口可以下载历史交易账单，通过对帐单核对后可以校对更正支付信息。

代码示例 - JAVA：

1
2    @Test
3    //Downloading Reconciliation API
4    public void downloadReconTest() throws IOException {
5        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/statements?date=20220401&mchid=1900000000");
6        httpGet.addHeader("Accept", "application/json");
7        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
8        CloseableHttpResponse response = httpClient.execute(httpGet);
9        //Process the response 
10    }
11

示例代码 - GO：

1
2//Download recon file API
3func downloadReconFile() {
4   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/statements?date=20220401&mchid=1900000000")
5   if err != nil {
6      // Process error
7   }
8   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
9}

示例代码 - PHP：

1
2//Downloading Reconciliation API
3public function downloadReconFile($instance){
4    try {
5        $resp = $instance
6            ->v3->global->statements
7            ->get([
8                'query' => [
9                    'date' => '20220401',
10                    'mchid' => '1900000000'
11                ]
12            ]);
13
14        echo $resp->getStatusCode(), PHP_EOL;
15        echo $resp->getBody(), PHP_EOL;
16    } catch (Exception $e) {
17        // Exception handling
18    }
19}

重要参数：

date: 账单日期, 格式：20180103

其他重要参数请前往下载对账单API文档页面参考。

3.2.7 关闭订单

步骤说明：下单超过5分钟后，可以调用该接口对下单未支付的订单进行关单操作，以便商户更换订单号重新下单发起支付或商户系统退出不再受理后避免用户继续支付。

代码示例 - JAVA：

1
2    @Test
3    //Call close order API
4    public void closeOrderTest() throws IOException {
5		String closeBody = String.join("\n" ,
6                		"{" ,
7                        "    'sp_mchid': '10000100'," ,
8                        "    'sub_mchid': '20000100'" ,
9                        "}").replace("'","\"");
10        HttpPost httpPost = new HttpPost("https://apihk.mch.weixin.qq.com/v3/global/transactions/out-trade-no/YX001/close");
11        httpPost.addHeader("Accept", "application/json");
12        httpPost.addHeader("Content-type", "application/json; charset=utf-8");
13        httpPost.setEntity(new StringEntity(closeBody));
14        CloseableHttpResponse response = httpClient.execute(httpPost);
15        System.out.println(response.getStatusLine().getStatusCode());
16    }
17

示例代码 - GO：

1
2//Call close order API
3func closeOrder() {
4   closeOrderBody := `{
5    "sp_mchid": "10000100",
6    "sub_mchid": "20000100"
7   }`
8   result, err := client.Post(ctx, "https://apihk.mch.weixin.qq.com/v3/global/transactions/out-trade-no/YX001/close", closeOrderBody)
9   if err != nil {
10      // Process error
11   }
12   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
13}

示例代码 - PHP：

1// Call close order API
2public function closeOrder($instance){
3    try {
4        $resp = $instance
5            ->v3->global->transactions->outTradeNo->_out_trade_no_->close
6            ->post([
7                'json' => [
8                'sp_mchid'     => '10000100',
9                'sub_mchid'    => '20000100'
10                ],
11                'out_trade_no' => 'YX0001'
12            ]);
13        echo $resp->getStatusCode(), PHP_EOL;
14        echo $resp->getBody(), PHP_EOL;
15    } catch (Exception $e) {
16        // Exception handling
17    }
18}

重要参数：

out_trade_no: 商户内部订单号

transaction_id: 微信支付订单号

可以用上述任一订单号进行查询。其他重要参数请前往关闭订单API文档页面参考。

3.2.8 下载平台证书

步骤说明：在调用其他接口之前，需要调用该接口下载平台证书用于对返回消息进行验签和返回消息中的加密字段进行解密。

代码示例 - JAVA：

1
2    @Test
3    //Call certificate downloading API
4    public void certDownloadingTest() throws IOException {
5        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/certificates");
6        httpGet.addHeader("Accept", "application/json");
7        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
8
9        CloseableHttpResponse response = httpClient.execute(httpGet);
10        //Process the response 
11//Get the response body: EntityUtils.toString(response.getEntity());
12//Get the response status code: response.getStatusLine().getStatusCode();
13
14        //Instead of calling the API to download platform certificate，
15        //We also recommend use the certificateMenager to get the valid certificate
16        verifier.getValidCertificate();
17    }
18

示例代码 - GO：

1
2//Calling download certificate API
3func downloadCert() {
4   result, err := client.Get((ctx, "https://apihk.mch.weixin.qq.com/v3/global/certificates"))
5   if err != nil {
6      if core.IsAPIError(err, "INVALID_REQUEST") {
7         //Process invalid request
8      }
9      // Process other error
10   }
11   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
12}

示例代码 - PHP：

1
2// Call download certificate API
3public function downloadCert($instance){
4    $resp = $instance->chain('v3/global/certificates')->get(
5        ['debug' => true] // debug mode，https://docs.guzzlephp.org/en/stable/request-options.html#debug
6    );
7    echo $resp->getBody(), PHP_EOL;
8}

重要参数：无

其他重要参数请前往下载平台证书API文档页面参考。

3.2.9 支付结果通知

步骤说明：用户完成支付后，微信支付会向下单时传入的notify_url推送支付结果通知，商户需要在接收到通知后返回对应的信息。

注意

  • 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。

  • 如果在所有通知频率(4小时)后没有收到微信侧回调，商户应调用查询订单接口确认订单状态。

 

特别提醒：机构系统对于支付结果通知的内容一定要做签名验证,并校验返回的订单金额是否与商户侧的订单金额一致，防止数据泄露导致出现“假通知”，造成资金损失。

3.2.9.1 通知规则

用户支付完成后，微信会把相关支付结果和用户信息发送给商户，商户需要接收处理后返回应答成功。只有支付成功才会通知。

对后台通知交互时，如果微信收到应答不是成功或超时，微信认为通知失败，微信会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但微信不保证通知最终能成功。 （通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m）

3.2.9.2 通知报文

支付结果通知是以“POST”方法访问商户设置的通知url，通知的数据以“JSON”格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情。

下面详细描述证书解密的流程

1、从商户平台上获取商户的密钥，记为“key”。

2、针对“algorithm”中描述的算法（目前为AEAD_AES_256_GCM），取得对应的参数“nonce”和“associated_data”。

3、使用“key”、“nonce”和“associated_data”对数据密文“ciphertext”进行解密（需要先对ciphertext做base64解码，然后再解密），得到证书内容

注意

AEAD_AES_256_GCM算法的接口细节，请参考rfc5116。微信支付使用的密钥key长度为32个字节，随机串nonce长度12个字节，associated_data长度小于16个字节并可能为空。

3.2.9.3 通知签名

加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考《微信支付API V3签名验证》。

3.2.9.4 回调示例

支付成功结果通知

1
2{
3    "id":"EV-2018022511223320873",
4    "create_time":"20180225112233",
5    "resource_type":"encrypt-resource",
6    "event_type":"TRANSACTION.SUCCESS",
7    "resource" : {
8        "algorithm":"AEAD_AES_256_GCM",
9        "ciphertext": "...",
10        "nonce": "...",
11        "associated_data": ""
12    }
13}
14

商户对resource对象进行解密后，得到的资源对象示例

1
2{
3    "id": "1008450740201411110005820873",
4    "sp_appid": "wx2421b1c4370ec43b",
5    "sp_mchid": "10000100",
6    "sub_mchid": "20000100",
7    "out_trade_no": "20150806125346",
8    "payer": {
9      "sp_openid": "oUpF8uN95-Ptaags6E_roPHg7AG0"
10    },
11    "amount" : {
12        "total": 528800,
13        "currency": "HKD",
14        "payer_total": 518799,
15        "payer_currency": "CNY",
16        "exchange_rate" : {
17            "type": "SETTLEMENT_RATE",
18            "rate": 8000000
19        }
20    },
21    "trade_type": "MICROPAY",
22    "trade_state": "SUCCESS",
23    "trade_state_desc": "支付成功",
24    "bank_type": "CCB_DEBIT",
25    "attach": "支付测试",
26    "success_time": "2018-06-08T10:34:56+08:00",
27    "promotion_detail":[
28        {
29            "promotion_id":"109519",
30            "name":"单品惠-6",
31            "scope":"SINGLE",
32            "type":"DISCOUNT",
33            "amount":1,
34            "currency":"HKD",
35            "activity_id":"931386",
36            "wechatpay_contribute_amount":1,
37            "merchant_contribute_amount":0,
38            "other_contribute_amount":0,
39            "goods_detail":[
40                {
41                    "goods_id":"iphone6s_16G",
42                    "goods_remark":"商品备注",
43                    "quantity":1,
44                    "price":528800
45                }
46            ]
47        }
48    ]
49}
50
3.2.9.5 通知应答

支付通知http应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx。

注意

当商户后台应答失败时，微信支付将记录下应答的报文，建议商户按照以下格式返回。

其他重要参数请前往支付结果通知API文档页面参考。

3.2.10 退款通知

步骤说明：退款状态改变后，微信会把相关退款结果发送给商户。

注意

  • 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。

  • 如果在所有通知频率(4小时)后没有收到微信侧回调，商户应调用查询订单接口确认订单状态。

 

特别提醒：机构系统对于支付结果通知的内容一定要做签名验证,并校验返回的订单金额是否与商户侧的订单金额一致，防止数据泄露导致出现“假通知”，造成资金损失。

3.2.10.1 通知规则

退款状态改变后，微信会把相关退款结果发送给商户。

对后台通知交互时，如果微信收到应答不是成功或超时，微信认为通知失败，微信会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但微信不保证通知最终能成功。 （通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m）

3.2.10.2 通知报文

退款结果通知是以“POST”方法访问商户设置的通知url，通知的数据以“JSON”格式通过请求主体（BODY）传输。通知的数据包括了加密的退款结果详情。

下面详细描述证书解密的流程

1、从商户平台上获取商户的密钥，记为“key”。

2、针对“algorithm”中描述的算法（目前为AEAD_AES_256_GCM），取得对应的参数“nonce”和“associated_data”。

3、使用“key”、“nonce”和“associated_data”对数据密文“ciphertext”进行解密（需要先对ciphertext做base64解码，然后再解密），得到证书内容

注意

AEAD_AES_256_GCM算法的接口细节，请参考rfc5116。微信支付使用的密钥key长度为32个字节，随机串nonce长度12个字节，associated_data长度小于16个字节并可能为空。

3.2.10.3 通知签名

加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考《微信支付API V3签名验证》。

3.2.10.4 回调示例

退款通知

1
2{
3	"id": "EV-2018022511223320873",
4	"create_time": "2018-06-08T10:34:56+08:00",
5	"resource_type": "encrypt-resource",
6	"event_type": "REFUND.SUCCESS",
7	"summary": "退款成功",
8	"resource": {
9		"original_type": "refund",
10		"algorithm": "AEAD_AES_256_GCM",
11		"ciphertext": "...",
12		"associated_data": "",
13		"nonce": "..."
14	}
15}
16

商户对resource对象进行解密后，得到的资源对象示例

1
2{
3    "sp_mchid": "1900000100",
4    "sub_mchid": "1900000109",
5    "transaction_id": "1008450740201411110005820873",
6    "out_trade_no": "20150806125346",
7    "refund_id": "50200207182018070300011301001",
8    "out_refund_no": "7752501201407033233368018",
9    "refund_status": "SUCCESS",
10    "success_time": "2018-06-08T10:34:56+08:00",
11    "recv_account": "招商银行信用卡0403",
12    "fund_source": "REFUND_SOURCE_UNSETTLED_FUNDS",
13    "amount" : {
14        "total": 528800,
15        "currency": "HKD",
16        "refund": 528800,
17        "payer_total": 528800,
18        "payer_refund": 528800,
19        "payer_currency": "HKD",
20        "exchange_rate" : {
21            "type": "SETTLEMENT_RATE",
22            "rate": 100000000
23        }
24    }
25}
26
3.2.10.5 通知应答

退款通知http应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx。

注意

当商户后台应答失败时，微信支付将记录下应答的报文，建议商户按照以下格式返回。

其他重要参数请前往退款通知API文档页面参考。

3.2.11 查询资金结算明细

步骤说明：商户在交易完结之后，可按结算日期查询已结算资金明细（sette_state为SETTLED），也可以查询未结算资金明细（sette_state为UNSETTLE）。

注意

该接口供跨境收单机构/直连商户使用，特别是，日本/澳门机构商户若开通香港钱包业务，需要对接该接口。

代码示例 - JAVA：

1
2    @Test
3    //Query Settlement API
4    public void querySettlementTest() throws IOException {
5        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/settle/settlements" +
6                "?sub_mchid=100012321&settle_state=SETTLED&settle_start_date=20221225" +
7                "&settle_end_date=20221226&offset=10&limit=5");
8        httpGet.addHeader("Accept", "application/json");
9        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
10        CloseableHttpResponse response = httpClient.execute(httpGet);
11        //Process the response 
12    }
13

示例代码 - GO：

1
2//Query settlement API
3func querySettlement() {
4   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/settle/settlements?sub_mchid=100012321&settle_state=SETTLED&settle_start_date=20221225&settle_end_date=20221226&offset=10&limit=5")
5   if err != nil {
6      // Process error
7   }
8   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
9}

示例代码 - PHP：

1
2//Querying Settlement Info API
3public function querySettlementInfo($instance){
4    try {
5        $resp = $instance
6            ->v3->global->settle->settlements
7            ->get(['query' => [
8                'sub_mchid' => '100012321',
9                'settle_state' => 'SETTLED',
10                'settle_start_date' => '20221225',
11                'settle_end_date' => '20221226',
12                'offset' => '10',
13                'limit' => '5'
14            ]]);
15
16        echo $resp->getStatusCode(), PHP_EOL;
17        echo $resp->getBody(), PHP_EOL;
18    } catch (\Exception $e) {
19        // Exception handling
20    }
21}

重要参数：

settle_state： 资金结算状态，枚举值：

SETTLED：已结算

UNSETTLE：未结算

其他重要参数请前往查询资金结算明细API文档页面参考。

4. H5支付获取用户IP指引

H5支付要求商户在统一下单接口中上传用户真实ip地址“spbill_create_ip”，为保证微信端获取的用户ip地址与商户端获取的一致，提供了以下获取用户ip的指引，希望对大家有所帮助。

没有代理的情况

在商户的前端接入层没有做代理的情况下获取ip的方式比较简单，直接获取'REMOTE_ADDR '即可。

有代理的情况

在有代理的情况下，因为要代替客户端去访问服务器，所以，当请求包经过反向代理后，在代理服务器这里这个IP数据包的IP包头做了修改，最终后端WEB服务器得到的数据包的头部源IP地址是代理服务器的IP地址。这样一来，后端服务器的程序就无法获取用户的真实ip。

 

nginx有代理的情况:

在nginx中配置中加入

1vi /usr/local/apache/conf/httpd.conf
2Include conf/extra/httpd-remoteip.conf
3vi /usr/local/apache/conf/extra/httpd-remoteip.conf
4LoadModule remoteip_module modules/mod_remoteip.so
5RemoteIPHeader X-Forwarded-For
6RemoteIPinternalProxy 127.0.0.1
7
8

 

Apache有代理的情况:

1proxy_set_header Host $host;
2proxy_set_header X-Real-IP $remote_addr;
3proxy_set_header X-Real-Port $remote_port;
4proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
5

 

代码示例

1
2string GetClientIp(CgiInput * poInput) {
3	string client_ip = "";
4	string strClientIPList;
5	GetHttpHeader("X-Forwarded-For", strClientIPList);
6
7	if (strClientIPList.empty()) {
8		GetHttpHeader("X-Real-IP", strClientIPList);
9	}
10
11	if (!strClientIPList.empty()) {
12		size_t iPos = strClientIPList.find(",");
13		if (iPos != std::string::npos) {
14			client_ip = strClientIPList.substr(iPos);
15		} else {
16			client_ip = strClientIPList;
17		}
18	}
19
20	if (client_ip.empty()) {
21		GetHttpHeader("PROXY_FORWARDED_FOR", strClientIPList);
22		// 做下兼容 
23		if (strClientIPList.empty()) {
24			client_ip = getRemoteAddr();
25		} else {
26			size_t iPos = strClientIPList.find(",");
27			if (iPos != std::string::npos) {
28				client_ip = strClientIPList.substr(iPos);
29			} else {
30				client_ip = strClientIPList;
31			}
32		}
33	}
34	if (!MMPayCommFunc::IsIp(client_ip))
35		client_ip = getRemoteAddr();
36	return client_ip;
37}
38

5. 常见问题

.

5.1 回调页面

正常流程用户支付完成后会返回至发起支付的页面，如需返回至指定页面，则可以在MWEB_URL后拼接上redirect_url参数，来指定回调页面。
如您希望用户支付完成后跳转至https://www.wechatpay.com.cn，则可以做如下处理：

1
2假设您通过统一下单接口获到的MWEB_URL= https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx20161110163838f231619da20804912345&package=1037687096
3
4则拼接后的地址为MWEB_URL= https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx20161110163838f231619da20804912345&package=1037687096&redirect_url=https%3A%2F%2Fwww.wechatpay.com.cn
注意：

1、需对redirect_url进行urlencode处理；

2、由于设置redirect_url后,回跳指定页面的操作可能发生在：1,微信支付中间页调起微信收银台后超过5秒 2,用户点击“取消支付“或支付完成后点“完成”按钮。因此无法保证页面回跳时，支付流程已结束，所以商户设置的redirect_url地址不能自动执行查单操作，应让用户去点击按钮触发查单操作。回跳页面展示效果可参考下图。

6. 其它常见错误

问题

问题说明

解决方案

网络环境未能通过安全验证，请稍后再试

  1. 商户侧统一下单传的终端IP(spbill_create_ip)与用户实际调起支付时微信侧检测到的终端IP不一致导致的，这个问题一般是商户在统一下单时没有传递正确的终端IP到spbill_create_ip导致，详细可参见客户端ip获取指引

  2. 统一下单与调起支付时的网络有变动，如统一下单时是WIFI网络，下单成功后切换成4G网络再调起支付，这样可能会引发我们的正常拦截，请保持网络环境一致的情况下重新发起支付流程

商家参数格式有误，请联系商家解决

  1. 当前调起H5支付的referer为空导致，一般是因为直接访问页面调起H5支付，请按正常流程进行页面跳转后发起支付，或自行抓包确认referer值是否为空

  2. 如果是APP里调起H5支付，需要在webview中手动设置referer，如( Map extraHeaders = new HashMap();extraHeaders.put("Referer", "商户申请H5时提交的授权域名");例如:http://www.baidu.com ))

商家存在未配置的参数，请联系商家解决

  1. 当前调起H5支付的域名（微信侧从referer中获取）与申请H5支付时提交的授权域名不一致，如需添加或修改授权域名，请登录商户号对应的商户平台，进入Development Configuration菜单,在Payment Authorization Config区域对Authorized Domain进行配置。

  2. 如果设置了回跳地址redirect_url，请确认设置的回跳地址的域名与申请H5支付时提交的授权域名是否一致

支付请求已失效，请重新发起支付

统一下单返回的MWEB_URL生成后，有效期为5分钟，如超时请重新生成MWEB_URL后再发起支付

请在微信外打开订单，进行支付

H5支付不能直接在微信客户端内调起，请在外部浏览器调起

IOS：签名验证失败
安卓：系统繁忙，请稍后再试

  1. 请确认同一个MWEB_URL只被一个微信号调起，如果不同微信号调起请重新下单生成新的MWEB_URL

  2. 如MWEB_URL有添加redirect_url，请确认参数拼接格式是否有误，是否有对redirect_url的值做urlencode,可对比以下例子格式：https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx20161110163838f231619da20804912345&package=1037687096&redirect_url=https%3A%2F%2Fwww.wechatpay.com.cn

 

1. 接口规则
2. 开发环境搭建
JAVA
2.1.1. 使用条件
2.1.2. 安装
2.1.3. 初始化
2.1.4. 通用功能
Golang
2.2.1. 使用条件
2.2.2. 安装
2.2.3. 初始化
2.2.4. 通用功能
PHP
2.3.1. 使用条件
2.3.2. 安装
2.3.3. 初始化
2.3.4. 通用功能
3. 业务时序图
3.1. 业务时序图
3.2. API接入示例
3.2.1 下单
3.2.2 查询订单
3.2.3 申请退款
3.2.4 查询单笔退款
3.2.5 查询所有退款
3.2.6 下载对账单
3.2.7 关闭订单
3.2.8 下载平台证书
3.2.9 支付结果通知
3.2.10 退款通知
3.2.11 查询资金结算明细
4. H5支付获取用户IP指引
没有代理的情况
有代理的情况
5. 常见问题
5.1 回调页面
6. 其它常见错误
语言
置顶

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2025 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

ICP证

粤B2-20090059

Contact Us

Customer Service Tel

+86 571 95017

9:00-18:00 Monday-Friday GMT+8

Business Development

wxpayglobal@tencent.com

Developer Support

wepayTS@tencent.com

Wechat Pay Global

About Tenpay
Powered By Tencent & Tenpay Copyright© 2005-2025 Tenpay All Rights Reserved.