WeChat Pay APIv3 Java SDK

To improve stability, the SDK supports dual-domain disaster recovery. If the primary domain api.mch.weixin.qq.com fails, the SDK can automatically switch to the backup domain api2.wechatpay.cn.

Recommended Strategy: To avoid increasing total retry counts and latency, it is recommended to combine disableRetryOnConnectionFailure() (to stop OkHttp from retrying multiple IPs on the same domain) and enableRetryMultiDomain() (to trigger the switch to the backup domain). This results in a retry sequence of [primary_ip1, backup_ip1] instead of exhausting all IPs on the primary domain first.

// Recommended: Enable dual-domain retry and disable OkHttp's default connection failure retry
HttpClient httpClient =
    new DefaultHttpClientBuilder()
        .config(config)
        .disableRetryOnConnectionFailure()
        .enableRetryMultiDomain()
        .build();

JsapiService service = new JsapiService.Builder().httpclient(httpClient).build();

To process callback notifications from WeChat Pay, you must create a public HTTP endpoint and use NotificationParser to verify and decrypt the payload.

Implementation Steps:

1. Construct RequestParam: Use the raw HTTP request body (do not use a serialized JSON string to avoid signature mismatches) and the following headers:
   • Wechatpay-Signature: The signature from WeChat Pay.
   • Wechatpay-Serial: The serial number of the platform certificate used for verification.
   • Wechatpay-Nonce: The nonce in the signature.
   • Wechatpay-Timestamp: The timestamp in the signature.
   • Wechatpay-Signature-Type: The signature type.
2. Initialize NotificationConfig: Choose one based on your security setup:
   • RSAPublicKeyNotificationConfig: If using WeChat Pay public/private keys.
   • RSAAutoCertificateConfig: If using the automatic platform certificate mechanism.
   • RSACombinedNotificationConfig: If performing a grayscale transition between platform certificates and public/private keys.
3. Initialize NotificationParser with the chosen config.
4. Parse the notification: Call NotificationParser.parse(requestParam, TargetClass.class). If verification fails, it throws a ValidationException.
5. Respond to WeChat Pay: Return 200 OK if processing succeeds. Return 4xx or 5xx (e.g., 500 Internal Server Error) if processing fails so WeChat Pay can retry.

Supported Notification Types:

• Payment: Transaction
• Refund: RefundNotification
• Unknown types: Use Map.class (nested JSON objects will be converted to LinkedTreeMap).

// 1. Construct RequestParam
RequestParam requestParam = new RequestParam.Builder()
        .serialNumber(wechatPaySerial)
        .nonce(wechatpayNonce)
        .signature(wechatSignature)
        .timestamp(wechatTimestamp)
        .body(requestBody)
        .build();

// 2. Initialize NotificationConfig (Example using RSAPublicKeyNotificationConfig)
NotificationConfig config = new RSAPublicKeyNotificationConfig.Builder()
        .publicKeyFromPath(publicKeyPath)
        .publicKeyId(publicKeyId)
        .apiV3Key(apiV3Key)
        .build();

// 3. Initialize NotificationParser
NotificationParser parser = new NotificationParser(config);

try {
  // 4. Parse (e.g., for a Transaction)
  Transaction transaction = parser.parse(requestParam, Transaction.class);
} catch (ValidationException e) {
  // Signature verification failed
  logger.error("sign verification failed", e);
  return ResponseEntity.status(HttpStatus.UNAUTHORIZED);
}

// 5. Handle business logic success/failure
if (/* process error */) {
  return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR);
}
return ResponseEntity.status(HttpStatus.OK);

While the SDK automatically handles encryption/decryption for supported interfaces (like Merchant Transfer), you can manually handle sensitive data using RSAPrivacyEncryptor and RSAPrivacyDecryptor.

Encryption (using a Public Key)

If you have the WeChat Pay public key (from platform certificates or the public key service):

PrivacyEncryptor encryptor = new RSAPrivacyEncryptor(wechatPayPublicKey);
String ciphertext = encryptor.encryptToString(plaintext);

If you are using RSAAutoCertificateConfig, you can obtain the encryptor and the required serial number directly from the config:

PrivacyEncryptor encryptor = config.createEncryptor();
String wechatPayCertificateSerialNumber = encryptor.getWechatpaySerial();
String ciphertext = encryptor.encryptToString(plaintext);

Decryption (using a Private Key)

To decrypt data using your merchant private key:

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

The SDK supports using Apache HttpClient via ApacheHttpClientAdapter. This is useful if you want to integrate with existing Apache HttpClient infrastructure. It automatically handles signature generation and verification.

Steps to use:

1. Initialize ApacheHttpClientAdapter using ApacheHttpClientBuilder.
2. Construct an HttpRequest using the HttpRequest.Builder.
3. Execute the request using httpClient.execute (supports GET, PUT, POST, PATCH, DELETE) or httpClient.get.

// 1. Initialize configuration
Config config = new RSAAutoCertificateConfig.Builder()
    .merchantId(merchantId)
    .privateKeyFromPath(privateKeyPath)
    .merchantSerialNumber(merchantSerialNumber)
    .apiV3Key(apiV3Key)
    .build();

// 2. Initialize ApacheHttpClient
HttpClient httpClient = new ApacheHttpClientBuilder().config(config).build();

// 3. Construct HttpRequest
HttpRequest httpRequest = new HttpRequest.Builder()
    .httpMethod(HttpMethod.GET)
    .url(requestPath)
    .headers(headers)
    .build();

// 4. Send request and receive response
HttpResponse<ExampleResponse> httpResponse = httpClient.execute(httpRequest, ExampleResponse.class);

The SDK uses OkHttp as the default HTTP client. You can use DefaultHttpClientBuilder to customize connection settings such as timeouts and proxies.

Available configuration methods:

• readTimeoutMs(long): Default 10000ms. Sets the default read timeout for new connections.
• writeTimeoutMs(long): Default 10000ms. Sets the default write timeout for new connections.
• connectTimeoutMs(long): Default 10000ms. Sets the default connection timeout for new connections.
• proxy(Proxy): Sets the HTTP proxy used when creating connections.
• disableRetryOnConnectionFailure(): Disables OkHttp's default retry on connection failure.
• enableRetryMultiDomain(): Enables automatic retry using the backup domain api2.wechatpay.cn if the primary domain api.mch.weixin.qq.com is unreachable.

HttpClient httpClient =
    new DefaultHttpClientBuilder()
        .config(config)
        .connectTimeoutMs(500)
        .build();

// Initialize a service (e.g., JsapiService) with the custom client
JsapiService service = new JsapiService.Builder().httpclient(httpClient).build();