0
# Notification Processing
1

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

4
## Capabilities
5

6
### Payment Notifications (API v2)
7

8
Parse and validate XML-based payment notifications.
9

10
```java { .api }
11
/**
12
 * Parse payment notification from WeChat Pay API v2
13
 * @param xmlData XML notification data from WeChat
14
 * @return Parsed payment notification result
15
 * @throws WxPayException if parsing or validation fails
16
 */
17
WxPayOrderNotifyResult parseOrderNotifyResult(String xmlData) throws WxPayException;
18
```
19

20
**Usage Example:**
21

22
```java
23
@PostMapping("/payment/notify")
24
public String handlePaymentNotify(HttpServletRequest request) {
25
    try {
26
        // Read XML data from request
27
        String xmlData = IOUtils.toString(request.getInputStream(), "UTF-8");
28
        
29
        // Parse notification
30
        WxPayOrderNotifyResult result = wxPayService.parseOrderNotifyResult(xmlData);
31
        
32
        // Verify payment success
33
        if ("SUCCESS".equals(result.getResultCode()) && "SUCCESS".equals(result.getReturnCode())) {
34
            // Process successful payment
35
            String outTradeNo = result.getOutTradeNo();
36
            String transactionId = result.getTransactionId();
37
            Integer totalFee = result.getTotalFee();
38
            
39
            // Update order status in your system
40
            updateOrderStatus(outTradeNo, "PAID");
41
            
42
            // Return success response to WeChat
43
            return "<xml><return_code><![CDATA[SUCCESS]]></return_code></xml>";
44
        }
45
    } catch (Exception e) {
46
        logger.error("Payment notification processing failed", e);
47
    }
48
    
49
    return "<xml><return_code><![CDATA[FAIL]]></return_code></xml>";
50
}
51
```
52

53
### Payment Notifications (API v3)
54

55
Parse and validate JSON-based payment notifications with enhanced security.
56

57
```java { .api }
58
/**
59
 * Parse payment notification from WeChat Pay API v3
60
 * @param jsonData JSON notification data from WeChat
61
 * @param header Signature header for validation
62
 * @return Parsed V3 payment notification result
63
 * @throws WxPayException if parsing or validation fails
64
 */
65
WxPayNotifyV3Result parseOrderNotifyV3Result(String jsonData, SignatureHeader header) throws WxPayException;
66
```
67

68
**Usage Example:**
69

70
```java
71
@PostMapping("/payment/notify/v3")
72
public String handlePaymentNotifyV3(HttpServletRequest request) {
73
    try {
74
        // Read JSON data
75
        String jsonData = IOUtils.toString(request.getInputStream(), "UTF-8");
76
        
77
        // Extract signature headers
78
        SignatureHeader header = new SignatureHeader();
79
        header.setTimeStamp(request.getHeader("Wechatpay-Timestamp"));
80
        header.setNonce(request.getHeader("Wechatpay-Nonce"));
81
        header.setSignature(request.getHeader("Wechatpay-Signature"));
82
        header.setSerial(request.getHeader("Wechatpay-Serial"));
83
        
84
        // Parse and validate notification
85
        WxPayNotifyV3Result result = wxPayService.parseOrderNotifyV3Result(jsonData, header);
86
        
87
        // Process successful payment
88
        if ("SUCCESS".equals(result.getTradeState())) {
89
            String outTradeNo = result.getOutTradeNo();
90
            String transactionId = result.getTransactionId();
91
            
92
            updateOrderStatus(outTradeNo, "PAID");
93
            
94
            return "{\"code\": \"SUCCESS\", \"message\": \"成功\"}";
95
        }
96
    } catch (Exception e) {
97
        logger.error("V3 payment notification processing failed", e);
98
    }
99
    
100
    return "{\"code\": \"FAIL\", \"message\": \"失败\"}";
101
}
102
```
103

104
### Refund Notifications
105

106
Parse refund status notifications from WeChat Pay.
107

108
```java { .api }
109
/**
110
 * Parse refund notification from WeChat Pay API v2
111
 * @param xmlData XML refund notification data
112
 * @return Parsed refund notification result
113
 * @throws WxPayException if parsing fails
114
 */
115
WxPayRefundNotifyResult parseRefundNotifyResult(String xmlData) throws WxPayException;
116

117
/**
118
 * Parse refund notification from WeChat Pay API v3
119
 * @param jsonData JSON refund notification data
120
 * @param header Signature header for validation
121
 * @return Parsed V3 refund notification result
122
 * @throws WxPayException if parsing fails
123
 */
124
WxPayRefundNotifyV3Result parseRefundNotifyV3Result(String jsonData, SignatureHeader header) throws WxPayException;
125
```
126

127
## Notification Result Types
128

129
### WxPayOrderNotifyResult (API v2)
130

131
```java { .api }
132
class WxPayOrderNotifyResult extends BaseWxPayResult {
133
    String transactionId;     // WeChat transaction ID
134
    String outTradeNo;        // Merchant order number
135
    String openid;            // User openid
136
    String tradeType;         // Payment type
137
    String bankType;          // Bank type
138
    Integer totalFee;         // Payment amount in cents
139
    String feeType;           // Currency type
140
    String timeEnd;           // Payment completion time
141
    String attach;            // Additional data
142
}
143
```
144

145
### WxPayNotifyV3Result (API v3)
146

147
```java { .api }
148
class WxPayNotifyV3Result {
149
    String tradeState;        // Payment status
150
    String transactionId;     // WeChat transaction ID
151
    String outTradeNo;        // Merchant order number
152
    String tradeType;         // Payment type
153
    String successTime;       // Payment success time
154
    Payer payer;              // Payer information
155
    Amount amount;            // Amount details
156
    
157
    static class Payer {
158
        String openid;        // User openid
159
    }
160
    
161
    static class Amount {
162
        Integer total;        // Total amount in cents
163
        String currency;      // Currency code
164
        Integer payerTotal;   // Payer amount
165
        String payerCurrency; // Payer currency
166
    }
167
}
168
```
169

170
### SignatureHeader
171

172
```java { .api }
173
class SignatureHeader {
174
    String timeStamp;         // Request timestamp
175
    String nonce;             // Random nonce
176
    String signature;         // Request signature
177
    String serial;            // Certificate serial number
178
    String algorithm;         // Signature algorithm
179
}
180
```
181

182
## Important Notes
183

184
### Security Validation
185
- All notifications are automatically signature-validated
186
- V3 notifications include additional timestamp validation
187
- Invalid signatures will throw `WxPayException`
188

189
### Response Requirements
190
- **API v2**: Return XML format with `return_code`
191
- **API v3**: Return JSON format with `code` and `message`
192
- Always return success response to prevent WeChat retry
193

194
### Error Handling
195
- Process notifications idempotently (handle duplicates)
196
- Log all notification processing for audit trails
197
- Return appropriate error responses for WeChat retry logic