0
# Core Payment Operations
1

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

4
## Capabilities
5

6
### Unified Order Creation (API v2)
7

8
Creates payment orders using WeChat Pay API v2 (XML-based). Supports all trade types including JSAPI, NATIVE, APP, and MWEB.
9

10
```java { .api }
11
/**
12
 * Creates a unified payment order using WeChat Pay API v2
13
 * @param request Order creation request with payment details
14
 * @return Order creation result with payment parameters
15
 * @throws WxPayException if order creation fails
16
 */
17
WxPayUnifiedOrderResult unifiedOrder(WxPayUnifiedOrderRequest request) throws WxPayException;
18
```
19

20
**Usage Example:**
21

22
```java
23
import com.github.binarywang.wxpay.bean.request.WxPayUnifiedOrderRequest;
24
import com.github.binarywang.wxpay.bean.result.WxPayUnifiedOrderResult;
25
import com.github.binarywang.wxpay.constant.WxPayConstants;
26

27
// Create unified order request
28
WxPayUnifiedOrderRequest request = WxPayUnifiedOrderRequest.newBuilder()
29
    .outTradeNo("ORDER_20230101_001")
30
    .totalFee(100) // Amount in cents (1.00 CNY)
31
    .body("Test Product Purchase")
32
    .tradeType(WxPayConstants.TradeType.JSAPI)
33
    .openid("user-openid-for-jsapi-payment")
34
    .notifyUrl("https://your-domain.com/payment/notify")
35
    .spbillCreateIp("192.168.1.1")
36
    .build();
37

38
// Execute order creation
39
WxPayUnifiedOrderResult result = wxPayService.unifiedOrder(request);
40

41
// Extract payment parameters for frontend
42
String prepayId = result.getPrepayId();
43
Map<String, String> payParams = result.getPayInfo();
44
```
45

46
### Unified Order Creation (API v3)
47

48
Creates payment orders using WeChat Pay API v3 (JSON-based) with enhanced security and additional features.
49

50
```java { .api }
51
/**
52
 * Creates a unified payment order using WeChat Pay API v3
53
 * @param tradeType Payment method type (JSAPI, NATIVE, APP, MWEB)
54
 * @param request Order creation request with payment details
55
 * @return Order creation result with payment parameters
56
 * @throws WxPayException if order creation fails
57
 */
58
WxPayUnifiedOrderV3Result unifiedOrderV3(TradeTypeEnum tradeType, WxPayUnifiedOrderV3Request request) throws WxPayException;
59
```
60

61
**Usage Example:**
62

63
```java
64
import com.github.binarywang.wxpay.bean.request.WxPayUnifiedOrderV3Request;
65
import com.github.binarywang.wxpay.bean.result.WxPayUnifiedOrderV3Result;
66
import com.github.binarywang.wxpay.bean.result.enums.TradeTypeEnum;
67

68
// Create V3 order request
69
WxPayUnifiedOrderV3Request request = new WxPayUnifiedOrderV3Request();
70
request.setOutTradeNo("ORDER_20230101_002");
71
request.setDescription("Premium Product Purchase");
72
request.setNotifyUrl("https://your-domain.com/payment/notify/v3");
73

74
// Set amount details
75
WxPayUnifiedOrderV3Request.Amount amount = new WxPayUnifiedOrderV3Request.Amount();
76
amount.setTotal(100); // Amount in cents
77
amount.setCurrency("CNY");
78
request.setAmount(amount);
79

80
// Set payer info for JSAPI
81
WxPayUnifiedOrderV3Request.Payer payer = new WxPayUnifiedOrderV3Request.Payer();
82
payer.setOpenid("user-openid-for-jsapi");
83
request.setPayer(payer);
84

85
// Execute V3 order creation
86
WxPayUnifiedOrderV3Result result = wxPayService.unifiedOrderV3(TradeTypeEnum.JSAPI, request);
87

88
// Extract payment parameters
89
String prepayId = result.getPrepayId();
90
Map<String, String> payParams = result.getPayInfo();
91
```
92

93
### Order Querying
94

95
Query payment order status and details using either transaction ID or merchant order number.
96

97
```java { .api }
98
/**
99
 * Query payment order by transaction ID or merchant order number
100
 * @param transactionId WeChat transaction ID (optional if outTradeNo provided)
101
 * @param outTradeNo Merchant order number (optional if transactionId provided)
102
 * @return Order query result with payment status and details
103
 * @throws WxPayException if query fails
104
 */
105
WxPayOrderQueryResult queryOrder(String transactionId, String outTradeNo) throws WxPayException;
106

107
/**
108
 * Query payment order using request object
109
 * @param request Order query request with search parameters
110
 * @return Order query result with payment status and details
111
 * @throws WxPayException if query fails
112
 */
113
WxPayOrderQueryResult queryOrder(WxPayOrderQueryRequest request) throws WxPayException;
114
```
115

116
**Usage Example:**
117

118
```java
119
import com.github.binarywang.wxpay.bean.result.WxPayOrderQueryResult;
120

121
// Query by merchant order number
122
WxPayOrderQueryResult result = wxPayService.queryOrder(null, "ORDER_20230101_001");
123

124
// Check payment status
125
if ("SUCCESS".equals(result.getTradeState())) {
126
    System.out.println("Payment successful");
127
    System.out.println("Transaction ID: " + result.getTransactionId());
128
    System.out.println("Total Fee: " + result.getTotalFee());
129
    System.out.println("Payment Time: " + result.getTimeEnd());
130
} else {
131
    System.out.println("Payment status: " + result.getTradeState());
132
}
133
```
134

135
### Order Querying (API v3)
136

137
Query payment orders using WeChat Pay API v3 with enhanced response data.
138

139
```java { .api }
140
/**
141
 * Query payment order using WeChat Pay API v3
142
 * @param request V3 order query request
143
 * @return V3 order query result with detailed payment information
144
 * @throws WxPayException if query fails
145
 */
146
WxPayOrderQueryV3Result queryOrderV3(WxPayOrderQueryV3Request request) throws WxPayException;
147
```
148

149
### Order Closing
150

151
Close unpaid orders to prevent future payment attempts.
152

153
```java { .api }
154
/**
155
 * Close an unpaid order
156
 * @param outTradeNo Merchant order number to close
157
 * @return Order close result
158
 * @throws WxPayException if close operation fails
159
 */
160
WxPayOrderCloseResult closeOrder(String outTradeNo) throws WxPayException;
161

162
/**
163
 * Close an unpaid order using request object
164
 * @param request Order close request
165
 * @return Order close result
166
 * @throws WxPayException if close operation fails
167
 */
168
WxPayOrderCloseResult closeOrder(WxPayOrderCloseRequest request) throws WxPayException;
169
```
170

171
**Usage Example:**
172

173
```java
174
// Close order by merchant order number
175
WxPayOrderCloseResult result = wxPayService.closeOrder("ORDER_20230101_001");
176

177
if ("SUCCESS".equals(result.getResultCode())) {
178
    System.out.println("Order closed successfully");
179
}
180
```
181

182
### Order Closing (API v3)
183

184
Close orders using WeChat Pay API v3. Note that v3 close operations do not return result objects.
185

186
```java { .api }
187
/**
188
 * Close an unpaid order using WeChat Pay API v3
189
 * @param outTradeNo Merchant order number to close
190
 * @throws WxPayException if close operation fails
191
 */
192
void closeOrderV3(String outTradeNo) throws WxPayException;
193

194
/**
195
 * Close an unpaid order using WeChat Pay API v3
196
 * @param request V3 order close request
197
 * @throws WxPayException if close operation fails
198
 */
199
void closeOrderV3(WxPayOrderCloseV3Request request) throws WxPayException;
200

201
/**
202
 * Close partner order using WeChat Pay API v3 (for service providers)
203
 * @param outTradeNo Merchant order number to close
204
 * @throws WxPayException if close operation fails
205
 */
206
void closePartnerOrderV3(String outTradeNo) throws WxPayException;
207

208
/**
209
 * Close partner order using WeChat Pay API v3 (for service providers)
210
 * @param request Partner order close request
211
 * @throws WxPayException if close operation fails
212
 */
213
void closePartnerOrderV3(WxPayPartnerOrderCloseV3Request request) throws WxPayException;
214
```
215

216
### Micropay (Barcode/QR Code Scanning)
217

218
Process payments using barcode or QR code scanning, where customers present their payment code to merchants.
219

220
```java { .api }
221
/**
222
 * Process micropay (barcode/QR scanning) payment
223
 * @param request Micropay request with auth code and payment details
224
 * @return Micropay result with payment status
225
 * @throws WxPayException if payment processing fails
226
 */
227
WxPayMicropayResult micropay(WxPayMicropayRequest request) throws WxPayException;
228

229
/**
230
 * Process codepay payment (alternative micropay method)
231
 * @param request Codepay request with payment details
232
 * @return Codepay result with payment status
233
 * @throws WxPayException if payment processing fails
234
 */
235
WxPayCodepayResult codepay(WxPayCodepayRequest request) throws WxPayException;
236
```
237

238
**Usage Example:**
239

240
```java
241
import com.github.binarywang.wxpay.bean.request.WxPayMicropayRequest;
242
import com.github.binarywang.wxpay.bean.result.WxPayMicropayResult;
243

244
// Create micropay request
245
WxPayMicropayRequest request = WxPayMicropayRequest.newBuilder()
246
    .outTradeNo("SCAN_ORDER_20230101_001")
247
    .totalFee(100) // Amount in cents
248
    .body("Scanned Product Purchase")
249
    .authCode("134567890123456789") // Customer's payment code
250
    .spbillCreateIp("192.168.1.1")
251
    .build();
252

253
// Process micropay
254
WxPayMicropayResult result = wxPayService.micropay(request);
255

256
// Check payment result
257
if ("SUCCESS".equals(result.getResultCode())) {
258
    System.out.println("Payment successful: " + result.getTransactionId());
259
} else if ("USERPAYING".equals(result.getErrCode())) {
260
    System.out.println("User is paying, please wait and query order status");
261
} else {
262
    System.out.println("Payment failed: " + result.getErrCodeDes());
263
}
264
```
265

266
### Order Reversal
267

268
Reverse or cancel orders, primarily used for barcode payment scenarios.
269

270
```java { .api }
271
/**
272
 * Reverse/cancel an order (API v2)
273
 * @param request Order reverse request
274
 * @return Order reverse result
275
 * @throws WxPayException if reverse operation fails
276
 */
277
WxPayOrderReverseResult reverseOrder(WxPayOrderReverseRequest request) throws WxPayException;
278

279
/**
280
 * Reverse/cancel an order (API v3)
281
 * @param request V3 order reverse request
282
 * @return V3 order reverse result
283
 * @throws WxPayException if reverse operation fails
284
 */
285
WxPayOrderReverseV3Result reverseOrderV3(WxPayOrderReverseV3Request request) throws WxPayException;
286

287
/**
288
 * Reverse/cancel an order by merchant order number (API v3)
289
 * @param outTradeNo Merchant order number to reverse
290
 * @return V3 order reverse result
291
 * @throws WxPayException if reverse operation fails
292
 */
293
WxPayOrderReverseV3Result reverseOrderV3(String outTradeNo) throws WxPayException;
294
```
295

296
## Request Types
297

298
### WxPayUnifiedOrderRequest (API v2)
299

300
```java { .api }
301
class WxPayUnifiedOrderRequest extends BaseWxPayRequest {
302
    // Required fields
303
    String outTradeNo;        // Merchant order number
304
    Integer totalFee;         // Payment amount in cents
305
    String body;              // Product description
306
    String tradeType;         // Payment type (JSAPI, NATIVE, APP, MWEB)
307
    String notifyUrl;         // Notification callback URL
308
    String spbillCreateIp;    // Client IP address
309
    
310
    // Conditional fields
311
    String openid;            // Required for JSAPI payments
312
    String productId;         // Required for NATIVE payments
313
    
314
    // Optional fields
315
    String detail;            // Product detail description
316
    String attach;            // Additional data
317
    String feeType;           // Currency type (default: CNY)
318
    String timeStart;         // Payment start time
319
    String timeExpire;        // Payment expiration time
320
    String goodsTag;          // Product tag
321
    
322
    // Builder pattern
323
    static WxPayUnifiedOrderRequestBuilder newBuilder();
324
}
325
```
326

327
### WxPayUnifiedOrderV3Request (API v3)
328

329
```java { .api }
330
class WxPayUnifiedOrderV3Request {
331
    String outTradeNo;        // Merchant order number
332
    String description;       // Product description
333
    String notifyUrl;         // Notification callback URL
334
    Amount amount;            // Payment amount details
335
    Payer payer;              // Payer information (for JSAPI)
336
    
337
    // Amount details
338
    static class Amount {
339
        Integer total;        // Total amount in cents
340
        String currency;      // Currency code (CNY)
341
    }
342
    
343
    // Payer information
344
    static class Payer {
345
        String openid;        // User openid for JSAPI payments
346
    }
347
}
348
```
349

350
## Result Types
351

352
### WxPayUnifiedOrderResult (API v2)
353

354
```java { .api }
355
class WxPayUnifiedOrderResult extends BaseWxPayResult {
356
    String prepayId;          // Prepayment ID
357
    String codeUrl;           // Payment QR code URL (for NATIVE)
358
    String mwebUrl;           // H5 payment URL (for MWEB)
359
    
360
    // Payment parameter generation
361
    Map<String, String> getPayInfo();
362
    WxPayAppOrderResult createAppOrder();
363
    WxPayMpOrderResult createMpOrder();
364
    WxPayNativeOrderResult createNativeOrder();
365
    WxPayH5OrderResult createH5Order();
366
}
367
```
368

369
### WxPayOrderQueryResult
370

371
```java { .api }
372
class WxPayOrderQueryResult extends BaseWxPayResult {
373
    String tradeState;        // Payment status (SUCCESS, REFUND, etc.)
374
    String transactionId;     // WeChat transaction ID
375
    String outTradeNo;        // Merchant order number
376
    Integer totalFee;         // Payment amount in cents
377
    String timeEnd;           // Payment completion time
378
    String tradeStateDesc;    // Payment status description
379
    String bankType;          // Bank type
380
    String feeType;           // Currency type
381
}
382
```
383

384
### Utility Methods
385

386
Additional utility methods for URL shortening, authentication, and QR code generation.
387

388
```java { .api }
389
/**
390
 * Shorten a long URL for WeChat Pay
391
 * @param longUrl Long URL to shorten
392
 * @return Shortened URL
393
 * @throws WxPayException if URL shortening fails
394
 */
395
String shorturl(String longUrl) throws WxPayException;
396

397
/**
398
 * Shorten URL using request object
399
 * @param request URL shortening request
400
 * @return Shortened URL
401
 * @throws WxPayException if URL shortening fails
402
 */
403
String shorturl(WxPayShorturlRequest request) throws WxPayException;
404

405
/**
406
 * Convert auth code to openid
407
 * @param authCode Authorization code from customer
408
 * @return User's openid
409
 * @throws WxPayException if conversion fails
410
 */
411
String authcode2Openid(String authCode) throws WxPayException;
412

413
/**
414
 * Convert auth code to openid using request object
415
 * @param request Auth code conversion request
416
 * @return User's openid
417
 * @throws WxPayException if conversion fails
418
 */
419
String authcode2Openid(WxPayAuthcode2OpenidRequest request) throws WxPayException;
420
```
421

422
**Usage Example:**
423

424
```java
425
// Shorten a payment URL
426
String longUrl = "https://pay.weixin.qq.com/wxpay/pay.action?prepay_id=wx20230101123456";
427
String shortUrl = wxPayService.shorturl(longUrl);
428

429
// Convert auth code to openid for user identification
430
String authCode = "134567890123456789"; // From customer scan
431
String openid = wxPayService.authcode2Openid(authCode);
432
```
433

434
### QR Code Generation
435

436
Generate QR codes for scan-and-pay scenarios.
437

438
```java { .api }
439
/**
440
 * Create QR code for scan pay mode 1 (customer scans merchant QR)
441
 * @param productId Product identifier
442
 * @return QR code content string
443
 */
444
String createScanPayQrcodeMode1(String productId);
445

446
/**
447
 * Create QR code image for scan pay mode 1 with logo
448
 * @param productId Product identifier
449
 * @param logoFile Logo image file to embed
450
 * @param sideLength QR code size in pixels
451
 * @return QR code image as byte array
452
 * @throws Exception if QR code generation fails
453
 */
454
byte[] createScanPayQrcodeMode1(String productId, File logoFile, Integer sideLength) throws Exception;
455

456
/**
457
 * Create QR code image for scan pay mode 2 (merchant scans customer QR)
458
 * @param codeUrl Code URL from unified order result
459
 * @param logoFile Logo image file to embed
460
 * @param sideLength QR code size in pixels
461
 * @return QR code image as byte array
462
 * @throws Exception if QR code generation fails
463
 */
464
byte[] createScanPayQrcodeMode2(String codeUrl, File logoFile, Integer sideLength) throws Exception;
465
```
466

467
## Common Payment Statuses
468

469
- **SUCCESS**: Payment successful
470
- **REFUND**: Order refunded
471
- **NOTPAY**: Order created but not paid
472
- **CLOSED**: Order closed
473
- **REVOKED**: Order revoked (barcode payment)
474
- **USERPAYING**: User paying (barcode payment)
475
- **PAYERROR**: Payment failed