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