开发指引

更新时间：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 get -u github.com/wechatpay-apiv3/wechatpay-go

来添加依赖，完成 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. 业务时序图

机构提交子商户进件申请后，微信支付将对该子商户的资料进行系统审核，并返回进件是否成功或需要进一步人工审核的状态，所以机构需要关注接口返回结果：

进件成功

1
2{
3	"sub_mchid": "20000100",
4	"verification_status": "Approved"
5}
6

进件失败

1
2{
3  "code": "INVALID_REQUEST",
4  "message": "Parameter format verification error",
5  "detail": {
6    "field": "#/properties/payer",
7    "value": "1346177081915535577",
8    "issue": "Does not match the ALLOF schema",
9    "location": "body"
10  }
11}
12

进件需进一步人工审核

1
2{
3  "sub_mchid": "20000100",
4  "verification_status": "Under Review",
5  "description": "This merchant takes effect only after being approved. Please check the verification status on WeChat Pay Merchant Platform."
6}
7

注意：此时该子商户没有支付权限，无法发起交易。需等待该子商户审核通过后，方可发起交易。机构可通过子商户查询接口，查询子商户的状态。

查询子商户状态

机构提交子商户进件申请后，可通过查询接口，查询子商户的状态：

OPERATING：正常；子商户已通过审核，入驻流程结束。其支付权限正常，可发起交易；

DEACTIVATED：已停用；该子商户在入驻审核通过后被机构自主停用，无支付权限，不能发起交易；

CLOSED：已关闭；该子商户在入驻审核通过后，被微信支付关闭支付权限，不能发起交易；

INCOMPLETE_APPLICATION：未完成入驻；子商户入驻申请未完成，无支付权限，不能发起交易。请于application_status字段查看入驻申请状态；

PENDING：待处理；该子商户在入驻审核通过后，其商户资料未通过日常复核，需要机构登录微信支付商户平台查看和处理。子商户权限正常，可发起交易。

子商户未完成入驻审核的处理

若查询到子商户状态为INCOMPLETE_APPLICATION，需进一步于application_status字段查看入驻申请状态：

UNDER_REVIEW：审核中；微信支付的审核人员正在审核该子商户的入驻申请，请耐心等待，可在一天后再次查询。如果申请完成后7个工作日后，状态仍为UNDER_REVIEW，可联系微信支付工作人员咨询；

REJECTED：已驳回；该子商户的入驻申请被微信支付驳回，需机构登录微信支付商户平台修改资料后重新提交（请于application_rejected_detail字段查看驳回原因）

3.2. API接入示例

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

注意

文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。
以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。

3.2.1 进件子商户

步骤说明：机构提交子商户资料，微信支付系统会为每个子商户创建子商户号。

敏感信息字段：对于包含了敏感信息的参数，如联系方式等，我们增加了“字段加密”的安全机制，保护敏感信息只能被数据的接收方看到。

加密方法

获取微信支付平台证书和对应的平台证书序列号，获取微信支付平台证书。本接口请求http头的“Wechatpay-Serial”需要传平台证书序列号。

使用微信支付平台证书的公钥，对于需要加密的参数值进行RSA加密。Java语言的加密方法的填充方案使用 RSA/ECB/PKCS1Padding ;PHP填充方式为OPENSSL_PKCS1_PADDING。
加密后的密文，使用base64编码后，作为请求中相应参数的值。

代码示例 - JAVA：

1
2    // Onboarding Sub-merchant API
3    public void onboardingSubMerchant() throws IOException {
4		String onboardingSubMerchantBody = """{
5	"sp_appid": "wx82ec4jy334ner1",
6    "sp_mchid": "2422128905",
7    "name": "testname",
8    "shortname": "shortname",
9    "office_phone": "13680534111",
10    "contact": {
11        "email": "gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==",  // sensitive field, encryption content
12        "name": "Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==",  // sensitive field, encryption content
13        "phone": "l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=="   // sensitive field, encryption content
14    }, 
15    "business_category": 343,
16    "merchant_country_code": "344",
17    "merchant_type": "ENTERPRISE",
18    "registration_certificate_number": "519723407213085723",
19    "registration_certificate_date": "2022-06-03",
20    "settlement_bank_number": "559304578245298347923856",
21    "business": {
22        "business_type": "ONLINE",
23        "mcc": "5344",
24        "mini_program": "flowerplus"
25    },
26    "director": {
27        "name": "Tom",
28        "number": "1234567890"
29    }
30}""";
31        HttpPost httpPost = new HttpPost("https://apihk.mch.weixin.qq.com/v3/global/merchants");
32        httpPost.addHeader("Accept", "application/json");
33        httpPost.addHeader("Content-type", "application/json; charset=utf-8");
34        httpPost.addHeader("Wechatpay-Serial", "0798ABFDCBXXXXXXXXXXXXXXXXXXXXXXX054A761");
35        httpPost.setEntity(new StringEntity(verifyIdInfoBody));
36        CloseableHttpResponse response = httpClient.execute(httpPost);
37        //Process the response
38    }
39

示例代码 - GO：

1
2// Onboarding Sub-merchant API
3func onboardingSubMerchant() {
4   onboardingSubMerchantBody := `{
5	"sp_appid": "wx82ec4jy334ner1",
6    "sp_mchid": "2422128905",
7    "name": "testname",
8    "shortname": "shortname",
9    "office_phone": "13680534111",
10    "contact": {
11        "email": "gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==",
12        "name": "Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==",
13        "phone": "l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=="
14    }, 
15    "business_category": 343,
16    "merchant_country_code": "344",
17    "merchant_type": "ENTERPRISE",
18    "registration_certificate_number": "519723407213085723",
19    "registration_certificate_date": "2022-06-03",
20    "settlement_bank_number": "559304578245298347923856",
21    "business": {
22        "business_type": "ONLINE",
23        "mcc": "5344",
24        "mini_program": "flowerplus"
25    },
26    "director": {
27        "name": "Tom",
28        "number": "1234567890"
29    }
30}`
31   header.Add("Wechatpay-Serial", "")
32   header.Add("Idempotency-Key", "20220518-001")
33   result, err := client.Post(ctx, "https://apihk.mch.weixin.qq.com/v3/global/merchants", header, nil, idVerificationBody, "application/json")
34   if err != nil {
35      // Process error
36   }
37   log.Printf("%s", result.Response.Body)
38}

示例代码 - PHP：

1
2// Onboarding Sub-merchant API
3public function onboardingSubMerchant($instance, $platformPublicKeyInstance, $platformCertificateSerial){
4    $encryptor = static function(string $msg) use ($platformPublicKeyInstance): string {
5        return Rsa::encrypt($msg, $platformPublicKeyInstance, OPENSSL_PKCS1_PADDING);
6    };
7    try {
8        $resp = $instance
9            ->chain('/v3/global/merchants')
10            ->post([
11                'json' => [
12                    'sp_appid' => 'wx82ec4jy334ner1',
13                    'sp_mchid' => '2422128905',
14                    'name' => 'testname',
15                    'shortname' => 'shortname',
16                    'office_phone' => '13680534111',
17                    'contact' => [
18                        'email' => 'gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==',
19                        'name' => 'Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==',
20                        'phone' => 'l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=='
21                    ],
22                    'business_category' => 343,
23                    'merchant_country_code' => '344',
24                    'merchant_type' => 'ENTERPRISE',
25                    'registration_certificate_number' => '519723407213085723',
26                    'registration_certificate_date' => '2022-06-03',
27                    'settlement_bank_number' => '559304578245298347923856',
28                    'business' => [
29                        'business_type' => 'ONLINE',
30                        'mcc' => '5344',
31                        'mini_program' => 'flowerplus'
32                    ],
33                    'director' => [
34                        'name' => 'Tom',
35                        'number' => '1234567890'
36                    ]
37                ],
38                'headers' => [
39                    'Wechatpay-Serial' => $platformCertificateSerial
40                ]
41            ]);
42        echo $resp->getStatusCode(), PHP_EOL;
43        echo $resp->getBody(), PHP_EOL;
44    } catch (\Exception $e) {
45        // Exception handling
46    }
47}

其他重要参数请前往进件子商户API文档页面参考。

3.2.2 查询子商户

步骤说明：用于机构查询子商户创建是否成功，接口只提供单个子商户信息查询。

代码示例 - JAVA：

1
2    // Query Sub-merchant API
3    public void querySubMerchant() throws IOException {
4        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/merchants/{$sub_mchid}?sp_appid=wx8888888888888888&sp_mchid=1900000100");
5        httpGet.addHeader("Accept", "application/json");
6        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
7        CloseableHttpResponse response = httpClient.execute(httpGet);
8        //Process the response 
9    }
10

示例代码 - GO：

1// Query Sub-merchant API
2func querySubMerchant() {
3   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/merchants/{$sub_mchid}?sp_appid=wx8888888888888888&sp_mchid=1900000100")
4   if err != nil {
5      // Process error
6   }
7   log.Printf("%s", result.Response.Body)
8}

示例代码 - PHP：

1// Query Sub-merchant API
2public function querySubMerchant($instance){
3    try {
4        $resp = $instance
5            ->chain('/v3/global/merchants/{$sub_mchid}')
6            ->get([
7                'query' => [
8                    'sp_appid' => 'wx8888888888888888',
9                    'sp_mchid' => '1900000100',
10                ]
11            ]);
12        echo $resp->getStatusCode(), PHP_EOL;
13        echo $resp->getBody(), PHP_EOL;
14    } catch (\Exception $e) {
15        // Exception handling
16    }
17}

其他重要参数请前往查询子商户API文档页面参考。

3.2.3 修改子商户

步骤说明：用于机构子商户创建成功后，接口提供子商户信息修改

敏感信息字段：对于包含了敏感信息的参数，如联系方式等，我们增加了“字段加密”的安全机制，保护敏感信息只能被数据的接收方看到。

加密方法

获取微信支付平台证书和对应的平台证书序列号，获取微信支付平台证书。本接口请求http头的“Wechatpay-Serial”需要传平台证书序列号。

使用微信支付平台证书的公钥，对于需要加密的参数值进行RSA加密。Java语言的加密方法的填充方案使用 RSA/ECB/PKCS1Padding ;PHP填充方式为OPENSSL_PKCS1_PADDING。
加密后的密文，使用base64编码后，作为请求中相应参数的值。

代码示例 - JAVA：

1
2// Sub Merchant Modifying API
3    public void modifySubMerchant() throws IOException {
4		String modifySubMerchantBody = """{
5	"sub_mchid": "20000100",
6	"sp_appid": "wx82ec4jy334ner1",
7    "sp_mchid": "2422128905",
8    "name": "testname",
9    "shortname": "shortname",
10    "office_phone": "13680534111",
11    "contact": {
12        "email": "gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==",  // sensitive field, encryption content
13        "name": "Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==",  // sensitive field, encryption content
14        "phone": "l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=="   // sensitive field, encryption content
15    }, 
16    "business_category": 343,
17    "merchant_country_code": "344",
18    "merchant_type": "ENTERPRISE",
19    "registration_certificate_number": "519723407213085723",
20    "registration_certificate_date": "2022-06-03",
21    "settlement_bank_number": "559304578245298347923856",
22    "business": {
23        "business_type": "ONLINE",
24        "mcc": "5344",
25        "mini_program": "flowerplus"
26    },
27    "director": {
28        "name": "Tom",
29        "number": "1234567890"
30    }
31}""";
32        httpPut httpPut = new httpPut("https://apihk.mch.weixin.qq.com/v3/global/merchants");
33        httpPut.addHeader("Accept", "application/json");
34        httpPut.addHeader("Content-type", "application/json; charset=utf-8");
35        httpPut.addHeader("Wechatpay-Serial", "0798ABFDCBXXXXXXXXXXXXXXXXXXXXXXX054A761");
36        httpPut.setEntity(new StringEntity(verifyIdInfoBody));
37        CloseableHttpResponse response = httpClient.execute(httpPut);
38        //Process the response
39    }
40

示例代码 - GO：

1
2// Sub Merchant Modifying API
3func modifySubMerchant() {
4   modifySubMerchantBody := `{
5	"sub_mchid": "20000100",
6	"sp_appid": "wx82ec4jy334ner1",
7    "sp_mchid": "2422128905",
8    "name": "testname",
9    "shortname": "shortname",
10    "office_phone": "13680534111",
11    "contact": {
12        "email": "gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==",
13        "name": "Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==",
14        "phone": "l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=="
15    }, 
16    "business_category": 343,
17    "merchant_country_code": "344",
18    "merchant_type": "ENTERPRISE",
19    "registration_certificate_number": "519723407213085723",
20    "registration_certificate_date": "2022-06-03",
21    "settlement_bank_number": "559304578245298347923856",
22    "business": {
23        "business_type": "ONLINE",
24        "mcc": "5344",
25        "mini_program": "flowerplus"
26    },
27    "director": {
28        "name": "Tom",
29        "number": "1234567890"
30    }
31}`
32   header.Add("Wechatpay-Serial", "")
33   header.Add("Idempotency-Key", "20220518-001")
34   result, err := client.Put(ctx, "https://apihk.mch.weixin.qq.com/v3/global/merchants", header, nil, idVerificationBody, "application/json")
35   if err != nil {
36      // Process error
37   }
38   log.Printf("%s", result.Response.Body)
39}

示例代码 - PHP：

1
2// Sub Merchant Modifying API
3public function modifySubMerchant($instance, $platformPublicKeyInstance, $platformCertificateSerial){
4    $encryptor = static function(string $msg) use ($platformPublicKeyInstance): string {
5        return Rsa::encrypt($msg, $platformPublicKeyInstance, OPENSSL_PKCS1_PADDING);
6    };
7    try {
8        $resp = $instance
9            ->chain('/v3/global/merchants')
10            ->put([
11                'json' => [
12					'sub_mchid': '20000100',
13                    'sp_appid' => 'wx82ec4jy334ner1',
14                    'sp_mchid' => '2422128905',
15                    'name' => 'testname',
16                    'shortname' => 'shortname',
17                    'office_phone' => '13680534111',
18                    'contact' => [
19                        'email' => 'gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==',
20                        'name' => 'Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==',
21                        'phone' => 'l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=='
22                    ],
23                    'business_category' => 343,
24                    'merchant_country_code' => '344',
25                    'merchant_type' => 'ENTERPRISE',
26                    'registration_certificate_number' => '519723407213085723',
27                    'registration_certificate_date' => '2022-06-03',
28                    'settlement_bank_number' => '559304578245298347923856',
29                    'business' => [
30                        'business_type' => 'ONLINE',
31                        'mcc' => '5344',
32                        'mini_program' => 'flowerplus'
33                    ],
34                    'director' => [
35                        'name' => 'Tom',
36                        'number' => '1234567890'
37                    ]
38                ],
39                'headers' => [
40                    'Wechatpay-Serial' => $platformCertificateSerial
41                ]
42            ]);
43        echo $resp->getStatusCode(), PHP_EOL;
44        echo $resp->getBody(), PHP_EOL;
45    } catch (\Exception $e) {
46        // Exception handling
47    }
48}

示例代码 - json：

1{
2"stock_id": "Python",
3"stock_creator_mchid": "123456",
4"limit": 10,
5}

其他重要参数请前往修改子商户API文档页面参考。

4. 通过子商户进件接口为子商户申请H5支付权限

对于H5支付的产品介绍，请阅读H5支付权限申请 / 产品介绍。

为方便机构在申请子商户时为子商户申请H5支付权限，我们在子商户进件/修改/查询API接口内融合了H5权限申请能力。

4.1. H5支付权限状态定义及状态转移

子商户进件/修改/查询API接口的回包中，使用 h5_authorization_state 表示子商户的H5支付权限状态；该状态会决定您应当对子商户进行何种操作：

● UNAUTHORIZED 未授权：子商户未在微信支付系统开通支付权限，请通过修改子商户接口填写H5申请资料为子商户申请H5支付权限；或者您也可以直接通过进件子商户接口填写H5申请资料，直接获得H5支付权限状态为UNDER_REVIEW的子商户；

● UNDER_REVIEW 审核中：您的H5支付权限申请单已受理，微信支付的审核人员将在3～5个工作日左右完成申请单审核；请通过查询子商户接口查询审核结果；

● REJECETED 已驳回：您的H5支付权限申请单被驳回，请通过查询子商户接口查询具体驳回原因后，通过修改子商户接口更新H5申请资料；

● APPROVED 已通过：您的H5支付权限申请已通过，H5支付权限已开通。如果您需要修改H5支付域名，请通过修改子商户接口更新域名（注意：域名会根据您的输入全量更新）；

● UNDER_PUNISHMENT 处罚中：子商户违反微信支付条例，处于被处罚阶段，请联系BD处理；

● APPLICATION_FAILED 申请失败：您的H5支付申请失败，请通过查询子商户接口查询失败原因后，通过修改子商户接口重新申请H5支付权限。

开发指引

1. 接口规则

2. 开发环境搭建

JAVA

2.1.1. 使用条件

2.1.2. 安装

2.1.3. 初始化

2.1.4. 通用功能

Golang

2.2.1. 使用条件

2.2.2. 安装

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

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

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 修改子商户

4. 通过子商户进件接口为子商户申请H5支付权限

4.1. H5支付权限状态定义及状态转移

4.2. 子商户进件申请H5权限业务序列图