0
# Payment Methods Integration
1

2
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.
3

4
## Capabilities
5

6
### JSAPI Payment (Mini Program / Official Account)
7

8
Payment within WeChat ecosystem using user's openid. Suitable for Mini Programs and Official Account web pages.
9

10
```java { .api }
11
/**
12
 * Create JSAPI payment order
13
 * @param request Unified order request with openid
14
 * @return Order result with payment parameters for frontend
15
 * @throws WxPayException if order creation fails
16
 */
17
WxPayUnifiedOrderResult unifiedOrder(WxPayUnifiedOrderRequest request) throws WxPayException;
18

19
/**
20
 * Generate JSAPI payment parameters for frontend
21
 * @param result Unified order result
22
 * @return Payment parameters for WeChat JSAPI
23
 */
24
WxPayMpOrderResult createMpOrder(WxPayUnifiedOrderResult result);
25
```
26

27
**Usage Example:**
28

29
```java
30
// Create JSAPI payment request
31
WxPayUnifiedOrderRequest request = WxPayUnifiedOrderRequest.newBuilder()
32
    .outTradeNo("ORDER_20230101_001")
33
    .totalFee(100)
34
    .body("Premium Service")
35
    .tradeType(WxPayConstants.TradeType.JSAPI)
36
    .openid("user-openid-from-wechat")
37
    .notifyUrl("https://your-domain.com/payment/notify")
38
    .spbillCreateIp("192.168.1.1")
39
    .build();
40

41
// Create order
42
WxPayUnifiedOrderResult result = wxPayService.unifiedOrder(request);
43

44
// Generate payment parameters for frontend
45
WxPayMpOrderResult mpOrder = result.createMpOrder();
46

47
// Return to frontend for WeChat Pay
48
Map<String, String> payParams = Map.of(
49
    "appId", mpOrder.getAppId(),
50
    "timeStamp", mpOrder.getTimeStamp(),
51
    "nonceStr", mpOrder.getNonceStr(),
52
    "package", mpOrder.getPackageVal(),
53
    "signType", mpOrder.getSignType(),
54
    "paySign", mpOrder.getPaySign()
55
);
56
```
57

58
### Native Payment (QR Code)
59

60
QR code-based payment for web applications and PC environments.
61

62
```java { .api }
63
/**
64
 * Create Native payment order with QR code
65
 * @param request Unified order request for Native payment
66
 * @return Order result with QR code URL
67
 * @throws WxPayException if order creation fails
68
 */
69
WxPayUnifiedOrderResult unifiedOrder(WxPayUnifiedOrderRequest request) throws WxPayException;
70

71
/**
72
 * Generate Native payment parameters
73
 * @param result Unified order result
74
 * @return Native payment result with QR code
75
 */
76
WxPayNativeOrderResult createNativeOrder(WxPayUnifiedOrderResult result);
77
```
78

79
**Usage Example:**
80

81
```java
82
// Create Native payment request
83
WxPayUnifiedOrderRequest request = WxPayUnifiedOrderRequest.newBuilder()
84
    .outTradeNo("ORDER_20230101_002")
85
    .totalFee(200)
86
    .body("Desktop Software License")
87
    .tradeType(WxPayConstants.TradeType.NATIVE)
88
    .productId("PRODUCT_001") // Required for Native payments
89
    .notifyUrl("https://your-domain.com/payment/notify")
90
    .spbillCreateIp("192.168.1.1")
91
    .build();
92

93
// Create order
94
WxPayUnifiedOrderResult result = wxPayService.unifiedOrder(request);
95

96
// Get QR code URL
97
String qrCodeUrl = result.getCodeUrl();
98

99
// Generate QR code image and display to user
100
System.out.println("QR Code URL: " + qrCodeUrl);
101
```
102

103
### APP Payment
104

105
Payment within mobile applications (Android/iOS).
106

107
```java { .api }
108
/**
109
 * Create APP payment order
110
 * @param request Unified order request for APP payment
111
 * @return Order result with payment parameters for mobile app
112
 * @throws WxPayException if order creation fails
113
 */
114
WxPayUnifiedOrderResult unifiedOrder(WxPayUnifiedOrderRequest request) throws WxPayException;
115

116
/**
117
 * Generate APP payment parameters for mobile SDK
118
 * @param result Unified order result
119
 * @return APP payment result with SDK parameters
120
 */
121
WxPayAppOrderResult createAppOrder(WxPayUnifiedOrderResult result);
122
```
123

124
**Usage Example:**
125

126
```java
127
// Create APP payment request
128
WxPayUnifiedOrderRequest request = WxPayUnifiedOrderRequest.newBuilder()
129
    .outTradeNo("ORDER_20230101_003")
130
    .totalFee(500)
131
    .body("Mobile App Premium Features")
132
    .tradeType(WxPayConstants.TradeType.APP)
133
    .notifyUrl("https://your-domain.com/payment/notify")
134
    .spbillCreateIp("192.168.1.1")
135
    .build();
136

137
// Create order
138
WxPayUnifiedOrderResult result = wxPayService.unifiedOrder(request);
139

140
// Generate payment parameters for mobile app
141
WxPayAppOrderResult appOrder = result.createAppOrder();
142

143
// Return to mobile app for WeChat Pay SDK
144
Map<String, String> payParams = Map.of(
145
    "appid", appOrder.getAppId(),
146
    "partnerid", appOrder.getPartnerId(),
147
    "prepayid", appOrder.getPrepayId(),
148
    "package", appOrder.getPackageVal(),
149
    "noncestr", appOrder.getNonceStr(),
150
    "timestamp", appOrder.getTimeStamp(),
151
    "sign", appOrder.getSign()
152
);
153
```
154

155
### H5 Payment (Mobile Web)
156

157
Payment in mobile web browsers outside of WeChat.
158

159
```java { .api }
160
/**
161
 * Create H5 payment order for mobile web
162
 * @param request Unified order request with scene info
163
 * @return Order result with H5 payment URL
164
 * @throws WxPayException if order creation fails
165
 */
166
WxPayUnifiedOrderResult unifiedOrder(WxPayUnifiedOrderRequest request) throws WxPayException;
167

168
/**
169
 * Generate H5 payment parameters
170
 * @param result Unified order result
171
 * @return H5 payment result with redirect URLs
172
 */
173
WxPayH5OrderResult createH5Order(WxPayUnifiedOrderResult result);
174
```
175

176
**Usage Example:**
177

178
```java
179
// Create H5 payment request
180
WxPayUnifiedOrderRequest request = WxPayUnifiedOrderRequest.newBuilder()
181
    .outTradeNo("ORDER_20230101_004")
182
    .totalFee(300)
183
    .body("Mobile Web Purchase")
184
    .tradeType(WxPayConstants.TradeType.MWEB)
185
    .notifyUrl("https://your-domain.com/payment/notify")
186
    .spbillCreateIp("192.168.1.1")
187
    // Scene info required for H5 payments
188
    .sceneInfo("{\"h5_info\": {\"type\":\"Wap\",\"wap_url\": \"https://your-domain.com\",\"wap_name\": \"Your Store\"}}")
189
    .build();
190

191
// Create order
192
WxPayUnifiedOrderResult result = wxPayService.unifiedOrder(request);
193

194
// Get H5 payment URL
195
String h5Url = result.getMwebUrl();
196

197
// Redirect user to WeChat Pay H5 page
198
System.out.println("H5 Payment URL: " + h5Url);
199
```
200

201
### Micropay (Barcode/QR Scanning)
202

203
Point-of-sale payment where merchant scans customer's WeChat payment code.
204

205
```java { .api }
206
/**
207
 * Process micropay transaction (barcode/QR scanning)
208
 * @param request Micropay request with customer's payment code
209
 * @return Micropay result with transaction details
210
 * @throws WxPayException if payment processing fails
211
 */
212
WxPayMicropayResult micropay(WxPayMicropayRequest request) throws WxPayException;
213
```
214

215
**Usage Example:**
216

217
```java
218
import com.github.binarywang.wxpay.bean.request.WxPayMicropayRequest;
219
import com.github.binarywang.wxpay.bean.result.WxPayMicropayResult;
220

221
// Create micropay request
222
WxPayMicropayRequest request = WxPayMicropayRequest.newBuilder()
223
    .outTradeNo("MICROPAY_20230101_001")
224
    .totalFee(150)
225
    .body("Coffee Shop Purchase")
226
    .authCode("130061234567890123") // Customer's payment code
227
    .spbillCreateIp("192.168.1.1")
228
    .build();
229

230
try {
231
    // Process payment
232
    WxPayMicropayResult result = wxPayService.micropay(request);
233
    
234
    if ("SUCCESS".equals(result.getResultCode()) && "SUCCESS".equals(result.getTradeState())) {
235
        System.out.println("Payment successful");
236
        System.out.println("Transaction ID: " + result.getTransactionId());
237
        System.out.println("Bank Type: " + result.getBankType());
238
    } else if ("USERPAYING".equals(result.getTradeState())) {
239
        // User is still paying, need to query order status
240
        System.out.println("User is paying, please wait...");
241
    }
242
} catch (WxPayException e) {
243
    System.out.println("Payment failed: " + e.getMessage());
244
}
245
```
246

247
### Face Payment
248

249
Facial recognition-based payment for authorized terminals.
250

251
```java { .api }
252
/**
253
 * Process face payment transaction
254
 * @param request Face payment request with biometric data
255
 * @return Face payment result with transaction details
256
 * @throws WxPayException if face payment processing fails
257
 */
258
WxPayFacepayResult facepay(WxPayFacepayRequest request) throws WxPayException;
259
```
260

261
**Usage Example:**
262

263
```java
264
// Create face payment request
265
WxPayFacepayRequest request = WxPayFacepayRequest.newBuilder()
266
    .outTradeNo("FACE_20230101_001")
267
    .totalFee(200)
268
    .body("Smart Store Purchase")
269
    .faceCode("face-recognition-token") // Face recognition result
270
    .spbillCreateIp("192.168.1.1")
271
    .build();
272

273
// Process face payment
274
WxPayFacepayResult result = wxPayService.facepay(request);
275

276
if ("SUCCESS".equals(result.getResultCode())) {
277
    System.out.println("Face payment successful");
278
    System.out.println("Transaction ID: " + result.getTransactionId());
279
}
280
```
281

282
## Payment Parameter Generation
283

284
### Generate Payment Parameters
285

286
Helper methods to generate frontend payment parameters from order results.
287

288
```java { .api }
289
/**
290
 * Generate payment parameters map
291
 * @return Payment parameters for frontend integration
292
 */
293
Map<String, String> getPayInfo();
294

295
/**
296
 * Create APP payment parameters
297
 * @return APP-specific payment parameters  
298
 */
299
WxPayAppOrderResult createAppOrder();
300

301
/**
302
 * Create Mini Program/Official Account payment parameters
303
 * @return JSAPI payment parameters
304
 */
305
WxPayMpOrderResult createMpOrder();
306

307
/**
308
 * Create Native payment parameters
309
 * @return Native payment parameters with QR code
310
 */
311
WxPayNativeOrderResult createNativeOrder();
312

313
/**
314
 * Create H5 payment parameters
315
 * @return H5 payment parameters with redirect URLs
316
 */
317
WxPayH5OrderResult createH5Order();
318
```
319

320
## Request Types
321

322
### WxPayMicropayRequest
323

324
```java { .api }
325
class WxPayMicropayRequest extends BaseWxPayRequest {
326
    String outTradeNo;        // Merchant order number
327
    Integer totalFee;         // Payment amount in cents
328
    String body;              // Product description
329
    String authCode;          // Customer's payment code (required)
330
    String spbillCreateIp;    // Client IP address
331
    
332
    // Optional fields
333
    String detail;            // Product detail
334
    String attach;            // Additional data
335
    String feeType;           // Currency type
336
    String goodsTag;          // Product tag
337
    String timeStart;         // Payment start time
338
    String timeExpire;        // Payment expiration time
339
    
340
    static WxPayMicropayRequestBuilder newBuilder();
341
}
342
```
343

344
### WxPayFacepayRequest
345

346
```java { .api }
347
class WxPayFacepayRequest extends BaseWxPayRequest {
348
    String outTradeNo;        // Merchant order number
349
    Integer totalFee;         // Payment amount in cents
350
    String body;              // Product description
351
    String faceCode;          // Face recognition token (required)
352
    String spbillCreateIp;    // Client IP address
353
    
354
    // Optional fields
355
    String detail;            // Product detail
356
    String attach;            // Additional data
357
    String feeType;           // Currency type
358
    
359
    static WxPayFacepayRequestBuilder newBuilder();
360
}
361
```
362

363
## Result Types
364

365
### WxPayMicropayResult
366

367
```java { .api }
368
class WxPayMicropayResult extends BaseWxPayResult {
369
    String tradeState;        // Payment status
370
    String transactionId;     // WeChat transaction ID
371
    String outTradeNo;        // Merchant order number
372
    Integer totalFee;         // Payment amount in cents
373
    String bankType;          // Bank type
374
    String openid;            // User openid
375
    String timeEnd;           // Payment completion time
376
    String tradeStateDesc;    // Status description
377
}
378
```
379

380
### WxPayAppOrderResult
381

382
```java { .api }
383
class WxPayAppOrderResult {
384
    String appId;             // Application ID
385
    String partnerId;         // Merchant ID
386
    String prepayId;          // Prepayment ID
387
    String packageVal;        // Package value
388
    String nonceStr;          // Random string
389
    String timeStamp;         // Timestamp
390
    String sign;              // Signature
391
}
392
```
393

394
### WxPayMpOrderResult
395

396
```java { .api }
397
class WxPayMpOrderResult {
398
    String appId;             // Application ID
399
    String timeStamp;         // Timestamp
400
    String nonceStr;          // Random string
401
    String packageVal;        // Package value
402
    String signType;          // Signature type
403
    String paySign;           // Payment signature
404
}
405
```
406

407
### WxPayNativeOrderResult
408

409
```java { .api }
410
class WxPayNativeOrderResult {
411
    String codeUrl;           // QR code URL
412
    String prepayId;          // Prepayment ID
413
}
414
```
415

416
### WxPayH5OrderResult
417

418
```java { .api }
419
class WxPayH5OrderResult {
420
    String mwebUrl;           // H5 payment URL
421
    String prepayId;          // Prepayment ID
422
}
423
```
424

425
## Trade Types and Constants
426

427
### WxPayConstants.TradeType
428

429
```java { .api }
430
class TradeType {
431
    String JSAPI = "JSAPI";   // Mini Program/Official Account
432
    String NATIVE = "NATIVE"; // QR Code payment
433
    String APP = "APP";       // Mobile app payment
434
    String MWEB = "MWEB";     // H5 mobile web payment
435
    String MICROPAY = "MICROPAY"; // Barcode scanning
436
    String FACEPAY = "FACEPAY";   // Face payment
437
}
438
```
439

440
## Payment Method Selection Guide
441

442
- **JSAPI**: Use for payments within WeChat ecosystem (Mini Programs, Official Accounts)
443
- **Native**: Best for desktop web applications and POS systems with QR code display
444
- **APP**: Ideal for mobile applications outside WeChat
445
- **H5 (MWEB)**: Suitable for mobile web browsers outside WeChat
446
- **Micropay**: Perfect for physical retail locations with barcode scanners
447
- **Face Payment**: Advanced option for authorized smart retail terminals
448

449
Each payment method requires specific configuration and has different integration requirements. Choose based on your platform and user experience needs.