0
# WeChat Payment Java SDK (weixin-java-pay)
1

2
WeChat Payment Java SDK is a comprehensive Java library for integrating with WeChat Pay (微信支付) services. It provides complete support for both WeChat Pay API v2 and v3, enabling developers to implement various payment functionalities including unified orders, refunds, enterprise payments, red packets, profit sharing, and marketing services with built-in security, certificate management, and multi-merchant support.
3

4
## Package Information
5

6
- **Package Name**: com.github.binarywang:weixin-java-pay
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `<dependency><groupId>com.github.binarywang</groupId><artifactId>weixin-java-pay</artifactId><version>4.7.0</version></dependency>`
10

11
## Core Imports
12

13
```java
14
import com.github.binarywang.wxpay.service.WxPayService;
15
import com.github.binarywang.wxpay.service.impl.WxPayServiceImpl;
16
import com.github.binarywang.wxpay.config.WxPayConfig;
17
```
18

19
For specific services:
20

21
```java
22
import com.github.binarywang.wxpay.service.EntPayService;
23
import com.github.binarywang.wxpay.service.RedpackService;
24
import com.github.binarywang.wxpay.service.ProfitSharingService;
25
```
26

27
For request/response beans:
28

29
```java
30
import com.github.binarywang.wxpay.bean.request.WxPayUnifiedOrderRequest;
31
import com.github.binarywang.wxpay.bean.result.WxPayUnifiedOrderResult;
32
import com.github.binarywang.wxpay.bean.notify.WxPayOrderNotifyResult;
33
```
34

35
## Basic Usage
36

37
```java
38
import com.github.binarywang.wxpay.service.WxPayService;
39
import com.github.binarywang.wxpay.service.impl.WxPayServiceImpl;
40
import com.github.binarywang.wxpay.config.WxPayConfig;
41
import com.github.binarywang.wxpay.bean.request.WxPayUnifiedOrderRequest;
42
import com.github.binarywang.wxpay.bean.result.WxPayUnifiedOrderResult;
43
import com.github.binarywang.wxpay.constant.WxPayConstants;
44

45
// Initialize configuration
46
WxPayConfig config = new WxPayConfig();
47
config.setAppId("your-app-id");
48
config.setMchId("your-merchant-id");
49
config.setMchKey("your-merchant-key");
50
config.setKeyPath("/path/to/cert.p12"); // Certificate path for secure operations
51

52
// Create service instance
53
WxPayService wxPayService = new WxPayServiceImpl();
54
wxPayService.setConfig(config);
55

56
// Create unified order for payment
57
WxPayUnifiedOrderRequest request = WxPayUnifiedOrderRequest.newBuilder()
58
    .outTradeNo("order-20230101-001")
59
    .totalFee(1) // Amount in cents
60
    .body("Test Product")
61
    .tradeType(WxPayConstants.TradeType.JSAPI)
62
    .openid("user-openid-for-jsapi")
63
    .build();
64

65
// Execute payment request
66
WxPayUnifiedOrderResult result = wxPayService.unifiedOrder(request);
67

68
// Extract payment parameters for frontend
69
Map<String, String> payParams = result.getPayInfo();
70
```
71

72
## Architecture
73

74
WeChat Payment Java SDK is built around several key components:
75

76
- **Service Layer**: Primary interfaces (`WxPayService`) and specialized services for different payment scenarios
77
- **Configuration Management**: `WxPayConfig` for merchant credentials, certificates, and environment settings
78
- **Request/Response Beans**: Strongly-typed objects for API communication with automatic XML/JSON serialization
79
- **Multi-Merchant Support**: Built-in support for managing multiple merchant configurations
80
- **Protocol Support**: Comprehensive support for both WeChat Pay API v2 (XML-based) and v3 (JSON-based)
81
- **Security Layer**: Certificate management, signature generation/validation, and encryption utilities
82
- **Notification Handling**: Webhook processing with signature verification for payment callbacks
83

84
## Capabilities
85

86
### Core Payment Operations
87

88
Essential payment processing functionality including order creation, querying, and cancellation. Supports all major WeChat Pay payment methods with both v2 and v3 API protocols.
89

90
```java { .api }
91
// Unified order creation (v2)
92
WxPayUnifiedOrderResult unifiedOrder(WxPayUnifiedOrderRequest request) throws WxPayException;
93

94
// Unified order creation (v3)
95
WxPayUnifiedOrderV3Result unifiedOrderV3(TradeTypeEnum tradeType, WxPayUnifiedOrderV3Request request) throws WxPayException;
96

97
// Order querying
98
WxPayOrderQueryResult queryOrder(String transactionId, String outTradeNo) throws WxPayException;
99

100
// Order closing
101
WxPayOrderCloseResult closeOrder(String outTradeNo) throws WxPayException;
102
```
103

104
[Core Payment Operations](./core-payment.md)
105

106
### Refund Management
107

108
Comprehensive refund processing with support for full and partial refunds, refund querying, and notification handling for both API versions.
109

110
```java { .api }
111
// Create refund (v2)
112
WxPayRefundResult refund(WxPayRefundRequest request) throws WxPayException;
113

114
// Create refund (v3)
115
WxPayRefundV3Result refundV3(WxPayRefundV3Request request) throws WxPayException;
116

117
// Query refund status
118
WxPayRefundQueryResult refundQuery(WxPayRefundQueryRequest request) throws WxPayException;
119
```
120

121
[Refund Management](./refund-management.md)
122

123
### Payment Methods Integration
124

125
Support for all WeChat Pay payment methods including JSAPI (Mini Program/Official Account), Native (QR Code), APP, H5 (Mobile Web), Micropay (Barcode), and Face Payment.
126

127
```java { .api }
128
// Micropay (barcode/QR scanning)
129
WxPayMicropayResult micropay(WxPayMicropayRequest request) throws WxPayException;
130

131
// Face payment
132
WxPayFacepayResult facepay(WxPayFacepayRequest request) throws WxPayException;
133

134
// Generate payment parameters for different platforms
135
Map<String, String> getPayInfo();
136
WxPayAppOrderResult createAppOrder(WxPayUnifiedOrderResult result);
137
WxPayMpOrderResult createMpOrder(WxPayUnifiedOrderResult result);
138
```
139

140
[Payment Methods](./payment-methods.md)
141

142
### Enterprise Services
143

144
Enterprise-level payment services including payments to individuals, red packet distribution, and profit sharing functionality.
145

146
```java { .api }
147
// Enterprise payments to individuals
148
EntPayResult entPay(EntPayRequest request) throws WxPayException;
149

150
// Red packet distribution
151
WxPaySendRedpackResult sendRedpack(WxPaySendRedpackRequest request) throws WxPayException;
152

153
// Profit sharing
154
ProfitSharingResult profitSharing(ProfitSharingRequest request) throws WxPayException;
155
```
156

157
[Enterprise Services](./enterprise-services.md)
158

159
### Configuration and Security
160

161
Configuration management, certificate handling, signature processing, and multi-merchant support for enterprise deployments.
162

163
```java { .api }
164
// Configuration management
165
void setConfig(WxPayConfig config);
166
void addConfig(String mchId, WxPayConfig wxPayConfig);
167
boolean switchover(String mchId);
168

169
// Certificate management
170
void initV3HttpClient() throws WxPayException;
171
String getCertSerialNo();
172

173
// Security utilities
174
String createSign(Map<String, String> params, SignType signType) throws WxPayException;
175
boolean checkSign(Map<String, String> params) throws WxPayException;
176
```
177

178
[Configuration and Security](./configuration-security.md)
179

180
### Notification Processing
181

182
Webhook processing for payment notifications with automatic signature verification and result parsing for various event types.
183

184
```java { .api }
185
// Parse payment notifications
186
WxPayOrderNotifyResult parseOrderNotifyResult(String xmlData) throws WxPayException;
187
WxPayNotifyV3Result parseOrderNotifyV3Result(String jsonData, SignatureHeader header) throws WxPayException;
188

189
// Parse refund notifications
190
WxPayRefundNotifyResult parseRefundNotifyResult(String xmlData) throws WxPayException;
191
WxPayRefundNotifyV3Result parseRefundNotifyV3Result(String jsonData, SignatureHeader header) throws WxPayException;
192
```
193

194
[Notification Processing](./notification-processing.md)
195

196
### Advanced Services
197

198
Specialized services including e-commerce platform support, marketing coupons, transfer services, Pay Score, complaint management, payroll, business circle, and bill downloads.
199

200
```java { .api }
201
// Marketing and coupons
202
MarketingFavorService getMarketingFavorService();
203
MarketingBusiFavorService getMarketingBusiFavorService();
204

205
// E-commerce platform
206
EcommerceService getEcommerceService();
207

208
// Transfer services
209
TransferService getTransferService();
210
MerchantTransferService getMerchantTransferService();
211
PartnerTransferService getPartnerTransferService();
212

213
// Pay Score services
214
PayScoreService getPayScoreService();
215
PartnerPayScoreService getPartnerPayScoreService();
216

217
// Payroll and business services
218
PayrollService getPayrollService();
219
BusinessCircleService getBusinessCircleService();
220

221
// Complaint management
222
ComplaintService getComplaintsService();
223

224
// Bill downloads
225
WxPayBillResult downloadBill(WxPayBillRequest request) throws WxPayException;
226
```
227

228
[Advanced Services](./advanced-services.md)
229

230
## Key Features Supported
231

232
### Payment Scenarios
233
- **B2C Payments**: Standard customer payments via all major channels
234
- **B2B Payments**: Business-to-business payment processing
235
- **C2B Payments**: Customer-initiated payments via QR codes and barcodes
236
- **Subscription Billing**: Recurring payment setups with entrust PAP
237
- **Multi-party Transactions**: Profit sharing among multiple recipients
238

239
### Business Functions
240
- **Order Management**: Complete lifecycle from creation to completion
241
- **Financial Operations**: Refunds, transfers, and settlement management
242
- **Marketing Tools**: Red packets, coupons, and promotional campaigns
243
- **Enterprise Features**: Payroll, expense reimbursements, and bulk transfers
244
- **Platform Services**: Multi-merchant and e-commerce platform support
245

246
### Technical Features
247
- **Protocol Flexibility**: Full support for both WeChat Pay v2 and v3 APIs
248
- **Security**: Certificate-based authentication, signature validation, encryption
249
- **Multi-tenant**: Support for multiple merchant configurations in single application
250
- **Error Handling**: Comprehensive exception handling with detailed error information
251
- **Thread Safety**: Concurrent request processing with proper resource management
252
- **Environment Support**: Production, sandbox, and development environment configurations