WeChat Pay APIv3 Java SDK

https://github.com/wechatpay-apiv3/wechatpay-java
Admin
The WeChat Pay APIv3 Java SDK is an official Java language client development library that provides...
Tokens:1,064,720
Snippets:5,624
Trust Score:6.6
License:Apache-2.0
Update:1 day ago
Show doc for...
Tokens:
Raw
### Usage example: execute GET request with HttpClient

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/core-http.md

Shows how to build an `HttpClient` using `DefaultHttpClientBuilder`, construct an `HttpRequest` with GET method and a trade bill URL, execute it with `QueryBillEntity` as the response class, and retrieve the service response entity.

```java
HttpClient httpClient = new DefaultHttpClientBuilder().config(config).build();
HttpRequest request = new HttpRequest.Builder()
        .httpMethod(HttpMethod.GET)
        .url("https://api.mch.weixin.qq.com/v3/bill/tradebill?bill_date=2023-01-01&bill_type=ALL")
        .build();
HttpResponse<QueryBillEntity> response = httpClient.execute(request, QueryBillEntity.class);
QueryBillEntity entity = response.getServiceResponse();
```

--------------------------------

### SMPemUtil usage example

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/shangmi.md

Example of loading an SM2 private key and an X509 certificate from file paths using SMPemUtil.

```java
PrivateKey sm2PrivateKey = SMPemUtil.loadPrivateKeyFromPath("/path/apiclient_key.pem");
X509Certificate cert = SMPemUtil.loadX509FromPath("/path/wechatpay_cert.pem");
```

--------------------------------

### CertificateService usage example

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/service-certificate.md

Shows how to build a CertificateService and download certificates either by passing the APIv3 key directly or by providing a custom AeadCipher (e.g., for SM4). The example then prints the serial number of each downloaded certificate.

```java
CertificateService service = new CertificateService.Builder().config(config).build();

// 方式一：直接传 APIv3 密钥
List<X509Certificate> certs = service.downloadCertificate(apiV3Key.getBytes(StandardCharsets.UTF_8));

// 方式二：自定义解密（如国密场景）
AeadCipher sm4Cipher = new AeadSM4Cipher(apiV3KeyBytes);
List<X509Certificate> smCerts = service.downloadCertificate(sm4Cipher);

for (X509Certificate cert : certs) {
  System.out.println(PemUtil.getSerialNumber(cert));
}
```

--------------------------------

### Usage example with timeouts and retry strategy

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/core-http.md

Shows how to build an HttpClient using DefaultHttpClientBuilder with a config, custom timeouts, and retry options. This example disables retry on connection failure and enables multi-domain retry.

```java
HttpClient httpClient = new DefaultHttpClientBuilder()
        .config(config)
        .connectTimeoutMs(500)
        .readTimeoutMs(3000)
        .disableRetryOnConnectionFailure()
        .enableRetryMultiDomain()
        .build();
```

--------------------------------

### Native 下单 + 查询 + 错误处理示例

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/service-payments.md

Complete usage example for Native payment: creates a NativePayService with a config, builds a PrepayRequest with amount, appid, mchid, description, notifyUrl, and outTradeNo, calls prepay to get a codeUrl, then queries the order by transaction ID and handles ServiceException by printing the error code and message.

```java
NativePayService service = new NativePayService.Builder().config(config).build();

PrepayRequest request = new PrepayRequest();
Amount amount = new Amount();
amount.setTotal(100);
request.setAmount(amount);
request.setAppid("wx1234567890abcdef");
request.setMchid("1900000109");
request.setDescription("测试商品");
request.setNotifyUrl("https://yourdomain.com/notify");
request.setOutTradeNo("out_trade_no_001");

PrepayResponse response = service.prepay(request);
System.out.println(response.getCodeUrl());

// 查询支付订单
QueryOrderByIdRequest queryRequest = new QueryOrderByIdRequest();
queryRequest.setMchid("1900000109");
queryRequest.setTransactionId("4200001569202208304701234567");
try {
  Transaction result = service.queryOrderById(queryRequest);
  System.out.println(result.getTradeState());
} catch (ServiceException e) {
  System.out.printf("code=[%s], message=[%s]%n", e.getErrorCode(), e.getErrorMessage());
}
```

--------------------------------

### Usage Example with Error Handling

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/core-http.md

Complete example of executing an HTTP request and handling errors using the WeChat Pay Java SDK.

```APIDOC
## Usage Example with Error Handling

### Description
Demonstrates how to execute an HTTP request using `HttpClient`, parse the response into a service object, and handle various exceptions.

### Code
```java
HttpClient httpClient = new DefaultHttpClientBuilder().config(config).build();
HttpRequest httpRequest = new HttpRequest.Builder()
        .httpMethod(HttpMethod.POST)
        .url("https://api.mch.weixin.qq.com/v3/refund/domestic/refunds")
        .body(new JsonRequestBody.Builder().body(toJson(createRequest)).build())
        .build();
try {
  HttpResponse<Refund> resp = httpClient.execute(httpRequest, Refund.class);
  Refund refund = resp.getServiceResponse();
} catch (ServiceException e) {
  System.out.printf("code=[%s], message=[%s]%n", e.getErrorCode(), e.getErrorMessage());
} catch (ValidationException e) {
  // 验签失败
} catch (HttpException e) {
  // 网络层失败，e.getHttpRequest() 可定位问题
}
```
```

--------------------------------

### Native payment order example using NativePayService.prepay()

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/README.md

This Java example shows how to configure the SDK with merchant credentials and call the prepay() method to create a Native payment order. It uses RSAPublicKeyConfig.Builder to build the config and NativePayService to send the request. The response contains a code_url that can be scanned by WeChat to complete the payment.

```java
package com.wechat.pay.java.service;

import com.wechat.pay.java.core.Config;
import com.wechat.pay.java.core.RSAAutoCertificateConfig;
import com.wechat.pay.java.service.payments.nativepay.NativePayService;
import com.wechat.pay.java.service.payments.nativepay.model.Amount;
import com.wechat.pay.java.service.payments.nativepay.model.PrepayRequest;
import com.wechat.pay.java.service.payments.nativepay.model.PrepayResponse;

/** Native 支付下单为例 */
public class QuickStart {

    /** 商户号 */
    public static String merchantId = "190000****";
    /** 商户API私钥路径 */
    public static String privateKeyPath = "/Users/yourname/your/path/apiclient_key.pem";
    /** 商户证书序列号 */
    public static String merchantSerialNumber = "5157F09EFDC096DE15EBE81A47057A72********";
    /** 商户APIV3密钥 */
    public static String apiV3Key = "...";

    public static void main(String[] args) {
        // 使用微信支付公钥的RSA配置
        Config config =
                new RSAPublicKeyConfig.Builder()
                        .merchantId(merchantId)
                        .privateKeyFromPath(privateKeyPath)
                        .publicKeyFromPath(publicKeyPath)
                        .publicKeyId(publicKeyId)
                        .merchantSerialNumber(merchantSerialNumber)
                        .apiV3Key(apiV3Key)
                        .build();
        // 构建service
        NativePayService service = new NativePayService.Builder().config(config).build();
        // request.setXxx(val)设置所需参数，具体参数可见Request定义
        PrepayRequest request = new PrepayRequest();
        Amount amount = new Amount();
        amount.setTotal(100);
        request.setAmount(amount);
        request.setAppid("wxa9d9651ae******");
        request.setMchid("190000****");
        request.setDescription("测试商品标题");
        request.setNotifyUrl("https://notify_url");
        request.setOutTradeNo("out_trade_no_001");
        // 调用下单方法，得到应答
        PrepayResponse response = service.prepay(request);
        // 使用微信扫描 code_url 对应的二维码，即可体验Native支付
        System.out.println(response.getCodeUrl());
    }
}
```

--------------------------------

### RSAAutoCertificateConfig usage example

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/core-config.md

Shows how to build a config and create a NativePayService. The build() method may throw an exception if certificate download fails, so it should be called during initialization.

```java
Config config = new RSAAutoCertificateConfig.Builder()
        .merchantId(merchantId)
        .privateKeyFromPath(privateKeyPath)
        .merchantSerialNumber(merchantSerialNumber)
        .apiV3Key(apiV3Key)
        .build();
NativePayService service = new NativePayService.Builder().config(config).build();
```

--------------------------------

### SMConfig usage example with NativePayService

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/shangmi.md

Shows how to build an `SMConfig` using the builder pattern with a private key from path and a WeChat Pay certificate from path, then create a `NativePayService` with that config. The private key must be an SM EC private key.

```java
Config config = new SMConfig.Builder()
        .merchantId(merchantId)
        .privateKeyFromPath(privateKeyPath)          // 国密 EC 私钥
        .merchantSerialNumber(merchantSerialNumber)
        .addWechatPayCertificateFromPath(certPath)
        .build();
NativePayService service = new NativePayService.Builder().config(config).build();
```

--------------------------------

### GET /v3/certificates (CertificateService)

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/endpoints.md

Downloads platform certificates. Returns a list of X509Certificate objects.

```APIDOC
## GET /v3/certificates

### Description
Downloads platform certificates.

### Method
GET

### Endpoint
/v3/certificates (constant `RSA_URL`)

### Response
#### Success Response (200)
- **List<X509Certificate>** - List of platform certificates.

### Service Methods
- `downloadCertificate(AeadCipher)`
- `downloadCertificate(byte[])`
```

--------------------------------

### RSAConfig usage example

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/core-config.md

Shows how to build an RSAConfig using the Builder. It sets the merchant ID, private key path, merchant serial number, and WeChat Pay certificate path.

```java
Config config = new RSAConfig.Builder()
        .merchantId(merchantId)
        .privateKeyFromPath(privateKeyPath)
        .merchantSerialNumber(merchantSerialNumber)
        .wechatPayCertificatesFromPath(wechatPayCertificatePath)
        .build();
```

--------------------------------

### Usage example: download and verify bill

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/service-billdownload.md

Shows how to use BillDownloadServiceExtension to download a trade bill with GZIP compression, consume the stream, and verify the hash. Throws IllegalStateException if verification fails.

```java
BillDownloadServiceExtension service =
    new BillDownloadServiceExtension.Builder().config(config).build();

GetTradeBillRequest request = new GetTradeBillRequest();
request.setBillDate("2023-01-01");
request.setTarType(TarType.GZIP);

DigestBillEntity entity = service.getTradeBill(request);
try (InputStream in = entity.getInputStream()) {
  // 消费账单流（写文件等）
}
if (!entity.verifyHash()) {
  // 摘要不一致：账单不完整或被篡改，应清理已保存文件
  throw new IllegalStateException("bill hash verification failed");
}
```

--------------------------------

### IOUtil usage example

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/core-util.md

Reads the response body from a download stream. Caution: not recommended for large bills.

```java
InputStream inputStream = httpClient.download(downloadUrl);
String respBody = IOUtil.toString(inputStream);   // 大账单请慎用
inputStream.close();
```

--------------------------------

### JsapiServiceExtension usage example

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/service-payments.md

Builds a JsapiServiceExtension with a config and signType "RSA" (the default), then calls prepayWithRequestPayment to obtain a response containing all parameters needed for JSAPI payment: appId, timeStamp, nonceStr, package, signType, and paySign.

```java
JsapiServiceExtension service = new JsapiServiceExtension.Builder()
        .config(config)
        .signType("RSA")          // 默认值，显式设置亦可
        .build();
PrepayWithRequestPaymentResponse response = service.prepayWithRequestPayment(request);
// response 含调起 JSAPI 支付所需全部参数：appId/timeStamp/nonceStr/package/signType/paySign
```

--------------------------------

### 构造 HttpRequest 并发送请求

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/README.md

构造 HttpRequest，以 GET 为例，设置 HTTP 方法和 URL 及请求头。然后通过 httpClient.execute 发送请求，并指定响应类型为 ExampleResponse。

```java
// 构造 HttpRequest，以 GET 为例
HttpRequest httpRequest =
  new HttpRequest.Builder()
  .httpMethod(HttpMethod.GET)
  .url(requestPath)
  .headers(headers)
  .build();

// 发送请求 Response 为自定义的回包的类型
HttpResponse<ExampleResponse> httpResponse = httpClient.execute(httpRequest, ExampleResponse.class);
```

--------------------------------

### HttpClient.get

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/core-http.md

发送 GET 请求。

```APIDOC
## HttpClient.get

### Description
发送 GET 请求。

### Method
- (interface method)

### Signature
```java
default <T> HttpResponse<T> get(HttpHeaders headers, String url, Class<T> responseClass);
```

### Parameters
- **headers** (HttpHeaders) - Required - HTTP 请求头
- **url** (String) - Required - 请求 URL
- **responseClass** (Class<T>) - Required - 响应类型
```

--------------------------------

### GET /v3/profitsharing/merchant-configs/{sub_mchid}

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/endpoints.md

Queries the profit sharing ratio configuration for a merchant.

```APIDOC
## GET /v3/profitsharing/merchant-configs/{sub_mchid}

### Description
Queries the profit sharing ratio configuration for a merchant.

### Method
GET

### Endpoint
/v3/profitsharing/merchant-configs/{sub_mchid}

### Parameters
#### Path Parameters
- **sub_mchid** (string) - Required - The sub-merchant ID.

### Response
#### Success Response
- **QueryMerchantRatioResponse** - The response containing the merchant ratio configuration.

### Service Method
`queryMerchantRatio`
```

--------------------------------

### RSAPublicKeyConfig usage example

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/core-config.md

Shows how to build an RSAPublicKeyConfig using the Builder. It sets the merchant ID, private key path, public key path, public key ID, merchant serial number, and API v3 key.

```java
Config config = new RSAPublicKeyConfig.Builder()
        .merchantId(merchantId)
        .privateKeyFromPath(privateKeyPath)
        .publicKeyFromPath(publicKeyPath)
        .publicKeyId(publicKeyId)
        .merchantSerialNumber(merchantSerialNumber)
        .apiV3Key(apiV3Key)
        .build();
```

--------------------------------

### Complete error-handling usage example

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/core-http.md

Shows how to execute a refund request and handle ServiceException, ValidationException (signature verification failure), and HttpException (network failure). The HttpRequest is built with POST method and a JSON request body.

```java
HttpClient httpClient = new DefaultHttpClientBuilder().config(config).build();
HttpRequest httpRequest = new HttpRequest.Builder()
        .httpMethod(HttpMethod.POST)
        .url("https://api.mch.weixin.qq.com/v3/refund/domestic/refunds")
        .body(new JsonRequestBody.Builder().body(toJson(createRequest)).build())
        .build();
try {
  HttpResponse<Refund> resp = httpClient.execute(httpRequest, Refund.class);
  Refund refund = resp.getServiceResponse();
} catch (ServiceException e) {
  System.out.printf("code=[%s], message=[%s]%n", e.getErrorCode(), e.getErrorMessage());
} catch (ValidationException e) {
  // 验签失败
} catch (HttpException e) {
  // 网络层失败，e.getHttpRequest() 可定位问题
}
```

--------------------------------

### PemUtil usage example

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/core-util.md

Loads a private key from a PEM file path, loads an X509 certificate from a PEM string, and retrieves its serial number in uppercase hexadecimal.

```java
PrivateKey privateKey = PemUtil.loadPrivateKeyFromPath("/path/apiclient_key.pem");
X509Certificate cert = PemUtil.loadX509FromString(pemString);
String serial = PemUtil.getSerialNumber(cert);
```

--------------------------------

### WechatPay2Credential usage example

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/core-auth.md

Shows how to create a `WechatPay2Credential` with an `RSASigner` and generate an authorization string for a POST request. This is typically called internally by the SDK, not directly by users.

```java
Signer signer = new RSASigner(merchantSerialNumber, privateKey);
Credential credential = new WechatPay2Credential(merchantId, signer);
String auth = credential.getAuthorization(
    URI.create("/v3/pay/transactions/native"), "POST", jsonBody);
```

--------------------------------

### Catching ServiceException example

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/errors.md

Shows how to catch ServiceException when calling a service method. Prints error code, message, and response body. For 5xx errors, retry is possible; otherwise report to monitoring.

```java
try {
  Transaction result = service.queryOrderById(queryRequest);
} catch (ServiceException e) {
  System.out.printf("code=[%s], message=[%s]%n", e.getErrorCode(), e.getErrorMessage());
  System.out.printf("reponse body=[%s]%n", e.getResponseBody());
  // 5xx：可主动重试；其他：上报监控
}
```

--------------------------------

### RSA signing and verification usage example

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/core-cipher.md

Demonstrates how to sign a message with RSASigner and verify with RSAVerifier. The signer returns a Base64 signature and the merchant certificate serial number. The verifier uses a WeChat Pay certificate provider and returns a boolean result.

```java
// 签名
Signer signer = new RSASigner(merchantSerialNumber, merchantPrivateKey);
SignatureResult result = signer.sign(message);
String sign = result.getSign();                         // Base64 签名
String serial = result.getCertificateSerialNumber();    // 商户证书序列号

// 验签
Verifier verifier = new RSAVerifier(wechatPayCertificateProvider);
boolean ok = verifier.verify(serialNumber, message, signature);
```

--------------------------------

### Manual Encryption and Decryption Example

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/core-cipher.md

Shows manual encryption and decryption using the config's createEncryptor() and a new RSAPrivacyDecryptor. The encryptor's getWechatpaySerial() provides the serial number for the Wechatpay-Serial header. The decryptor requires the merchant private key.

```java
Config config = new RSAAutoCertificateConfig.Builder()...build();
PrivacyEncryptor encryptor = config.createEncryptor();
String wechatPaySerial = encryptor.getWechatpaySerial();   // 设置到 Wechatpay-Serial 头
String ciphertext = encryptor.encrypt(plaintext);

PrivacyDecryptor decryptor = new RSAPrivacyDecryptor(merchantPrivateKey);
String plaintext = decryptor.decrypt(ciphertext);
```

--------------------------------

### JsapiServiceExtension.prepayWithRequestPayment(PrepayRequest request)

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/service-payments.md

Creates a JSAPI payment and returns the parameters needed to invoke the payment on the frontend. This method internally calls prepay to get the prepay_id, then generates the payment parameters including appId, timeStamp, nonceStr, package, signType, and paySign.

```APIDOC
## [POST] /v3/pay/transactions/jsapi (with payment parameters generation)

### Description
Creates a JSAPI payment and returns the parameters needed to invoke the payment on the frontend. This method internally calls prepay to get the prepay_id, then generates the payment parameters including appId, timeStamp, nonceStr, package, signType, and paySign.

### Method
POST

### Endpoint
/v3/pay/transactions/jsapi

### Parameters
#### Request Body
- **request** (PrepayRequest) - Required - The prepay request object containing payment details.

### Request Example
```java
JsapiServiceExtension service = new JsapiServiceExtension.Builder()
        .config(config)
        .signType("RSA")          // 默认值，显式设置亦可
        .build();
PrepayWithRequestPaymentResponse response = service.prepayWithRequestPayment(request);
```

### Response
#### Success Response (200)
- **appId** (string) - The app ID.
- **timeStamp** (string) - The timestamp in seconds.
- **nonceStr** (string) - The random string.
- **packageVal** (string) - The package value, formatted as "prepay_id=...".
- **signType** (string) - The signature type, default "RSA".
- **paySign** (string) - The payment signature.

#### Response Example
```json
{
  "appId": "wx8888888888888888",
  "timeStamp": "1609459200",
  "nonceStr": "abc123...",
  "packageVal": "prepay_id=wx201410272009395522657a690389285100",
  "signType": "RSA",
  "paySign": "..."
}
```
```

--------------------------------

### queryByOutRefundNo(QueryByOutRefundNoRequest) - GET /v3/refund/domestic/refunds/{out_refund_no}

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/service-refund.md

Queries a single refund by the merchant refund number. This method sends a GET request to the specified endpoint and returns a Refund object containing the refund details.

```APIDOC
## [GET] /v3/refund/domestic/refunds/{out_refund_no}

### Description
Queries a single refund by the merchant refund number.

### Method
GET

### Endpoint
/v3/refund/domestic/refunds/{out_refund_no}

### Parameters
#### Path Parameters
- **out_refund_no** (String) - Required - Merchant refund number

#### Query Parameters
- **sub_mchid** (String) - Optional - Sub-merchant ID

### Request Example
GET /v3/refund/domestic/refunds/out_refund_no_001?sub_mchid=1230000109

### Response
#### Success Response (200)
- **refund_id** (String) - WeChat refund ID
- **out_refund_no** (String) - Merchant refund number
- **transaction_id** (String) - WeChat Pay transaction ID
- **out_trade_no** (String) - Merchant order number
- **user_received_account** (String) - Refund receiving account
- **success_time** (String) - Refund success time
- **create_time** (String) - Refund creation time
- **promotion_detail** (List<Promotion>) - Promotion refund details
- **amount** (Amount) - Amount details
- **channel** (Channel) - Refund channel (ORIGINAL/BALANCE/OTHER_BALANCE/OTHER_BANKCARD)
- **funds_account** (FundsAccount) - Refund funds account
- **status** (Status) - Refund status

#### Response Example
{
  "refund_id": "50000000382019052709732678859",
  "out_refund_no": "out_refund_no_001",
  "transaction_id": "4200000984201905271858260918",
  "out_trade_no": "out_trade_no_001",
  "user_received_account": "支付用户零钱",
  "success_time": "2020-12-01T16:09:00+08:00",
  "create_time": "2020-12-01T16:09:00+08:00",
  "amount": {
    "total": 100,
    "refund": 1,
    "payer_total": 100,
    "payer_refund": 1
  },
  "channel": "ORIGINAL",
  "status": "SUCCESS"
}
```

--------------------------------

### GET /v3/pay/transactions/out-trade-no/{out_trade_no}

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/service-payments.md

通过商户订单号查询订单状态。

```APIDOC
## [GET] /v3/pay/transactions/out-trade-no/{out_trade_no}

### Description
通过商户订单号查询订单状态。

### Method
GET

### Endpoint
https://api.mch.weixin.qq.com/v3/pay/transactions/out-trade-no/{out_trade_no}

### Parameters
#### Path Parameters
- `out_trade_no` (string) - 必填 - 商户订单号

#### Query Parameters
- `mchid` (string) - 必填 - 商户号

### Request Example
```
GET /v3/pay/transactions/out-trade-no/out_trade_no_001?mchid=1900000109
```

### Response
#### Success Response (200)
- `tradeState` (string) - 交易状态

#### Response Example
```json
{
  "tradeState": "SUCCESS"
}
```
```

--------------------------------

### GET /v3/pay/transactions/id/{transaction_id}

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/service-payments.md

通过微信支付订单号查询订单状态。

```APIDOC
## [GET] /v3/pay/transactions/id/{transaction_id}

### Description
通过微信支付订单号查询订单状态。

### Method
GET

### Endpoint
https://api.mch.weixin.qq.com/v3/pay/transactions/id/{transaction_id}

### Parameters
#### Path Parameters
- `transaction_id` (string) - 必填 - 微信支付订单号

#### Query Parameters
- `mchid` (string) - 必填 - 商户号

### Request Example
```
GET /v3/pay/transactions/id/4200001569202208304701234567?mchid=1900000109
```

### Response
#### Success Response (200)
- `tradeState` (string) - 交易状态

#### Response Example
```json
{
  "tradeState": "SUCCESS"
}
```
```

--------------------------------

### BillDownloadService.getTradeBill

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/service-billdownload.md

获取交易账单。该方法通过 GET 请求访问 /v3/bill/tradebill 接口，返回账单申请结果。

```APIDOC
## [GET] /v3/bill/tradebill

### Description
获取交易账单。

### Method
GET

### Endpoint
https://api.mch.weixin.qq.com/v3/bill/tradebill

### Parameters
#### Request Body
- **billDate** (string) - Required - 账单日期，格式为 YYYY-MM-DD。
- **subMchid** (string) - Optional - 子商户号。
- **billType** (string) - Optional - 账单类型。
- **tarType** (TarType) - Optional - 压缩类型，如 GZIP。

### Request Example
{
  "billDate": "2023-01-01",
  "subMchid": "1234567890",
  "billType": "ALL",
  "tarType": "GZIP"
}

### Response
#### Success Response (200)
- **hashType** (HashType) - 摘要类型。
- **hashValue** (string) - 摘要值。
- **downloadUrl** (string) - 账单下载链接。

#### Response Example
{
  "hashType": "SHA1",
  "hashValue": "...",
  "downloadUrl": "https://..."
}
```

--------------------------------

### initiateBatchTransfer

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/service-transfer.md

发起批量转账。

```APIDOC
## POST /v3/transfer/batches

### Description
发起批量转账。

### Method
POST

### Endpoint
https://api.mch.weixin.qq.com/v3/transfer/batches

### Parameters
#### Request Body
- **InitiateBatchTransferRequest** - 请求参数

### Response
#### Success Response (200)
- **InitiateBatchTransferResponse** - 响应信息

```

--------------------------------

### Error handling for build() failure

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/core-config.md

Wrap the build() call in a try-catch to handle certificate download failures (e.g., wrong merchant parameters, network issues). Log the error and abort startup to avoid running with incorrect configuration.

```java
try {
  config = new RSAAutoCertificateConfig.Builder()...build();
} catch (Exception e) {
  // 记录日志并中断启动，避免携带错误配置进入线上
}
```

--------------------------------

### BillDownloadService.getAllSubMchFundFlowBill

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/service-billdownload.md

获取二级商户资金账单。该方法通过 GET 请求访问 /v3/ecommerce/bill/fundflowbill 接口，返回加密账单结果。

```APIDOC
## [GET] /v3/ecommerce/bill/fundflowbill

### Description
获取二级商户资金账单。

### Method
GET

### Endpoint
https://api.mch.weixin.qq.com/v3/ecommerce/bill/fundflowbill

### Parameters
#### Request Body
- **billDate** (string) - Required - 账单日期，格式为 YYYY-MM-DD。
- **tarType** (TarType) - Optional - 压缩类型，如 GZIP。

### Request Example
{
  "billDate": "2023-01-01",
  "tarType": "GZIP"
}

### Response
#### Success Response (200)
- **hashType** (HashType) - 摘要类型。
- **hashValue** (string) - 摘要值。
- **downloadUrl** (string) - 账单下载链接。
- **@Encryption** (object) - 加密的敏感字段。

#### Response Example
{
  "hashType": "SHA1",
  "hashValue": "...",
  "downloadUrl": "https://...",
  "@Encryption": {}
}
```

--------------------------------

### BillDownloadService.getSingleSubMchFundFlowBill

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/service-billdownload.md

获取子商户资金账单。该方法通过 GET 请求访问 /v3/bill/sub-merchant-fundflowbill 接口，返回加密账单结果。

```APIDOC
## [GET] /v3/bill/sub-merchant-fundflowbill

### Description
获取子商户资金账单。

### Method
GET

### Endpoint
https://api.mch.weixin.qq.com/v3/bill/sub-merchant-fundflowbill

### Parameters
#### Request Body
- **subMchid** (string) - Required - 子商户号。
- **billDate** (string) - Required - 账单日期，格式为 YYYY-MM-DD。
- **accountType** (string) - Optional - 资金账户类型。
- **algorithm** (string) - Optional - 加密算法。
- **tarType** (TarType) - Optional - 压缩类型，如 GZIP。

### Request Example
{
  "subMchid": "1234567890",
  "billDate": "2023-01-01",
  "accountType": "BASIC",
  "algorithm": "AEAD_AES_256_GCM",
  "tarType": "GZIP"
}

### Response
#### Success Response (200)
- **hashType** (HashType) - 摘要类型。
- **hashValue** (string) - 摘要值。
- **downloadUrl** (string) - 账单下载链接。
- **@Encryption** (object) - 加密的敏感字段。

#### Response Example
{
  "hashType": "SHA1",
  "hashValue": "...",
  "downloadUrl": "https://...",
  "@Encryption": {}
}
```

--------------------------------

### Gradle 依赖配置

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/shangmi/README.md

在 build.gradle 文件中添加 wechatpay-java 和 wechatpay-java-shangmi 的依赖。

```groovy
implementation 'com.github.wechatpay-apiv3:wechatpay-java:0.2.2'
implementation 'com.github.wechatpay-apiv3:wechatpay-java-shangmi:0.2.2'
```

--------------------------------

### BillDownloadService.getFundFlowBill

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/service-billdownload.md

获取资金账单。该方法通过 GET 请求访问 /v3/bill/fundflowbill 接口，返回账单申请结果。

```APIDOC
## [GET] /v3/bill/fundflowbill

### Description
获取资金账单。

### Method
GET

### Endpoint
https://api.mch.weixin.qq.com/v3/bill/fundflowbill

### Parameters
#### Request Body
- **billDate** (string) - Required - 账单日期，格式为 YYYY-MM-DD。
- **accountType** (string) - Optional - 资金账户类型。
- **tarType** (TarType) - Optional - 压缩类型，如 GZIP。

### Request Example
{
  "billDate": "2023-01-01",
  "accountType": "BASIC",
  "tarType": "GZIP"
}

### Response
#### Success Response (200)
- **hashType** (HashType) - 摘要类型。
- **hashValue** (string) - 摘要值。
- **downloadUrl** (string) - 账单下载链接。

#### Response Example
{
  "hashType": "SHA1",
  "hashValue": "...",
  "downloadUrl": "https://..."
}
```

--------------------------------

### Usage example for unregistering a merchant's auto-update task

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/core-certificate.md

Shows how to clean up a merchant's automatic update task using unregister. The shutdown call is commented out as a global cleanup example, typically for test environments. This service is usually called internally by RSAAutoCertificateConfig.

```java
// 通常由 RSAAutoCertificateConfig 内部调用，无需手动使用
AutoCertificateService.unregister(merchantId, "RSA");   // 清理某个商户的自动更新任务
// AutoCertificateService.shutdown();                    // 全局清理（例如测试环境）
```

--------------------------------

### Configure merchant information with RSAAutoCertificateConfig

Source: https://github.com/wechatpay-apiv3/wechatpay-java/wiki/代码示例片段

Sets up the SDK config with merchant ID, private key path, merchant serial number, and APIv3 key, then initializes a JsapiService using that config.

```java
Config config =
    new RSAAutoCertificateConfig.Builder()
        .merchantId(merchantId)
        .privateKeyFromPath(privateKeyPath)
        .merchantSerialNumber(merchantSerialNumber)
        .apiV3Key(apiV3key)
        .build();

// 以JsapiService为例，使用 config 初始化 service
JsapiService service = new JsapiService.Builder().config(config).build();
```

--------------------------------

### 下载账单文件并读取内容

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/README.md

使用 HttpClient.download() 方法下载账单文件，返回输入流。开发者使用完输入流后应自主关闭流。非压缩的账单可使用 IOUtil.toString() 从流读入内存字符串，大账单请慎用。下载后应使用账单摘要校验文件完整性。

```java
InputStream inputStream = httpClient.download(downloadUrl);

// 非压缩的账单可使用 core.util.IOUtil 从流读入内存字符串，大账单请慎用
String respBody = IOUtil.toString(inputStream);
inputStream.close();
```

--------------------------------

### GET /v3/transfer/batches/out-batch-no/{out_batch_no}

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/endpoints.md

Queries a transfer batch by the out-batch number.

```APIDOC
## GET /v3/transfer/batches/out-batch-no/{out_batch_no}

### Description
Queries a transfer batch by the out-batch number.

### Method
GET

### Endpoint
/v3/transfer/batches/out-batch-no/{out_batch_no}

### Parameters
#### Path Parameters
- **out_batch_no** (string) - Required - The out-batch number.

#### Query Parameters
- **need_query_detail** (boolean) - Optional - Whether to query the batch details.

### Response
#### Success Response
- **TransferBatchEntity** - The transfer batch entity.

### Service Method
`getTransferBatchByOutNo`
```

--------------------------------

### GET /v3/transfer/batches/batch-id/{batch_id}

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/endpoints.md

Queries a transfer batch by the batch ID.

```APIDOC
## GET /v3/transfer/batches/batch-id/{batch_id}

### Description
Queries a transfer batch by the batch ID.

### Method
GET

### Endpoint
/v3/transfer/batches/batch-id/{batch_id}

### Parameters
#### Path Parameters
- **batch_id** (string) - Required - The batch ID.

#### Query Parameters
- **need_query_detail** (boolean) - Optional - Whether to query the batch details.

### Response
#### Success Response
- **TransferBatchEntity** - The transfer batch entity.

### Service Method
`getTransferBatchByNo`
```

--------------------------------

### Initialize config with local public key using RSAPublicKeyConfig

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/README.md

Use this snippet to configure the SDK with a local WeChat Pay public key and public key ID for verifying responses and callbacks. The builder requires merchantId, privateKeyFromPath, publicKeyFromPath, publicKeyId, merchantSerialNumber, and apiV3Key. The comment notes you can use publicKeyFromPath or publicKey to load the public key.

```java
// 可以根据实际情况使用publicKeyFromPath或publicKey加载公钥
Config config =
    new RSAPublicKeyConfig.Builder()
        .merchantId(merchantId)
        .privateKeyFromPath(privateKeyPath)
        .publicKeyFromPath(publicKeyPath)
        .publicKeyId(publicKeyId)
        .merchantSerialNumber(merchantSerialNumber)
        .apiV3Key(apiV3Key)
        .build();
```

--------------------------------

### splitBill

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/service-profitsharing.md

Requests a profit sharing bill. Corresponds to GET /v3/profitsharing/bills.

```APIDOC
## GET /v3/profitsharing/bills

### Description
Requests a profit sharing bill.

### Method
GET

### Endpoint
https://api.mch.weixin.qq.com/v3/profitsharing/bills

### Parameters
#### Query Parameters
- **bill_date** (string) - Required - Bill date (YYYY-MM-DD)
- **sub_mchid** (string) - Optional - Sub-merchant ID
- **bill_type** (string) - Optional - Bill type
- **tar_type** (string) - Optional - Tar type

### Response
#### Success Response (200)
- **download_url** (string) - Download URL
- **hash_type** (string) - Hash type
- **hash_value** (string) - Hash value

#### Response Example
{
  "download_url": "https://...",
  "hash_type": "SHA1",
  "hash_value": "..."
}
```

--------------------------------

### Create JSAPI order and generate payment parameters

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/README.md

Use JsapiServiceExtension to create a JSAPI payment order and obtain the parameters needed to invoke payment on the frontend. The prepayWithRequestPayment method returns a PrepayWithRequestPaymentResponse containing all required parameters.

```java
JsapiServiceExtension service = new JsapiServiceExtension.Builder().config(config).build();

// 跟之前下单示例一样，填充预下单参数
PrepayRequest request = new PrepayRequest();

// response包含了调起支付所需的所有参数，可直接用于前端调起支付
PrepayWithRequestPaymentResponse response = service.prepayWithRequestPayment(request);
```

--------------------------------

### GET /v3/profitsharing/orders/{transaction_id}/amounts

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/endpoints.md

Queries the remaining amount of a profit sharing order.

```APIDOC
## GET /v3/profitsharing/orders/{transaction_id}/amounts

### Description
Queries the remaining amount of a profit sharing order.

### Method
GET

### Endpoint
/v3/profitsharing/orders/{transaction_id}/amounts

### Parameters
#### Path Parameters
- **transaction_id** (string) - Required - The transaction ID.

### Response
#### Success Response
- **QueryOrderAmountResponse** - The response containing the order amount information.

### Service Method
`queryOrderAmount`
```

--------------------------------

### queryOrder

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/service-profitsharing.md

Queries the result of a profit sharing order. Corresponds to GET /v3/profitsharing/orders/{out_order_no}.

```APIDOC
## GET /v3/profitsharing/orders/{out_order_no}

### Description
Queries the result of a profit sharing order.

### Method
GET

### Endpoint
https://api.mch.weixin.qq.com/v3/profitsharing/orders/{out_order_no}

### Parameters
#### Path Parameters
- **out_order_no** (string) - Required - Merchant order number

#### Query Parameters
- **sub_mchid** (string) - Optional - Sub-merchant ID
- **transaction_id** (string) - Required - Transaction ID

### Response
#### Success Response (200)
- **transaction_id** (string) - Transaction ID
- **out_order_no** (string) - Merchant order number
- **status** (string) - Order status
- **receivers** (array) - List of receivers

#### Response Example
{
  "transaction_id": "4200001234202401010000000000",
  "out_order_no": "P2024010100001",
  "status": "FINISHED",
  "receivers": []
}
```

--------------------------------

### GsonUtil usage example

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/core-util.md

Converts an object to JSON, automatically converting camelCase fields to snake_case.

```java
String json = GsonUtil.toJson(requestObject);   // 驼峰字段自动转下划线
```

--------------------------------

### 发起批量转账（initiateBatchTransfer）

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/api-reference/service-transfer.md

展示如何构造 InitiateBatchTransferRequest 并调用 initiateBatchTransfer 方法发起批量转账，包括设置转账场景、明细列表等参数。

```APIDOC
## initiateBatchTransfer 发起批量转账

### Description
通过 TransferBatchService 发起批量转账请求，返回包含批次号的响应。

### 方法
POST（SDK 方法调用）

### 调用方式
```java
TransferBatchService service = new TransferBatchService.Builder().config(config).build();

InitiateBatchTransferRequest request = new InitiateBatchTransferRequest();
request.setAppid("wx1234567890abcdef");
request.setOutBatchNo("pl20220123456");
request.setBatchName("2019年1月第1批");
request.setBatchRemark("测试转账");
request.setTotalAmount(3L);
request.setTotalNum(3);
request.setTransferSceneId("1000");
request.setNotifyUrl("https://yourdomain.com/transfer-notify");

TransferDetailInput detail = new TransferDetailInput();
detail.setOutDetailNo("x23zy545Bd5436");
detail.setTransferAmount(1L);
detail.setTransferRemark("测试明细");
detail.setOpenid("o-MYE42l80oelYMDE34nYD456Xoy");
request.setTransferDetailList(Collections.singletonList(detail));

InitiateBatchTransferResponse response = service.initiateBatchTransfer(request);
System.out.println(response.getBatchId());
```

### 请求参数

#### InitiateBatchTransferRequest
- **appid** (String) - 必填 - 商户 appid
- **outBatchNo** (String) - 必填 - 商户批次单号
- **batchName** (String) - 必填 - 批次名称
- **batchRemark** (String) - 必填 - 批次备注
- **totalAmount** (Long) - 必填 - 转账总金额（单位：分）
- **totalNum** (Integer) - 必填 - 转账总笔数
- **transferSceneId** (String) - 必填 - 转账场景 ID
- **notifyUrl** (String) - 可选 - 回调通知 URL
- **transferDetailList** (List<TransferDetailInput>) - 必填 - 转账明细列表

#### TransferDetailInput
- **outDetailNo** (String) - 必填 - 商户明细单号
- **transferAmount** (Long) - 必填 - 转账金额（单位：分）
- **transferRemark** (String) - 必填 - 转账备注
- **openid** (String) - 必填 - 收款用户 openid
- **userName** (String) - 可选 - 收款用户姓名（敏感字段，自动加密）

### 响应

#### InitiateBatchTransferResponse
- **batchId** (String) - 微信批次单号

### 响应示例
```java
System.out.println(response.getBatchId());
```

```

--------------------------------

### GET /v3/ecommerce/bill/fundflowbill

Source: https://github.com/wechatpay-apiv3/wechatpay-java/blob/main/_autodocs/endpoints.md

Downloads fund flow bills for all sub-merchants. Requires bill_date and optional tar_type.

```APIDOC
## GET /v3/ecommerce/bill/fundflowbill

### Description
Downloads fund flow bills for all sub-merchants.

### Method
GET

### Endpoint
/v3/ecommerce/bill/fundflowbill

### Parameters
#### Query Parameters
- **bill_date** (string) - Required - Bill date in YYYY-MM-DD format.
- **tar_type** (string) - Optional - Tar type.

### Response
#### Success Response (200)
- **QueryEncryptBillEntity** - The encrypted bill download information.

### Service Method
`getAllSubMchFundFlowBill`
```

--------------------------------

### 业务请求时沿用下载证书的网络配置

Source: https://github.com/wechatpay-apiv3/wechatpay-java/wiki/SDK-配置详解

将 Config 设置到 clientBuilder 中，构建 Service 可用的 HTTP 客户端，继续使用下载证书时的网络配置。

```java
// case1: 继续使用网络配置 
clientBuilder.config(config);
JsapiService service = new JsapiService.Builder()
        .httpclient(clientBuilder.build())
        .build();
```
Tokens:
Raw