# Payment Callback Safety

> 当代码涉及支付回调、webhook 通知、notify_url、微信支付/支付宝回调处理时触发。防止回调伪造、重放攻击、金额篡改等支付安全问题。

- Skill: `doccker/payment-callback-safety` (Agent Skill)
- Install (CLI): `npx skillmds@latest add doccker/payment-callback-safety`
- Raw SKILL.md: https://api.skillmd.com/api/skills/doccker/payment-callback-safety/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: doccker (https://skillmd.com/u/doccker)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/doccker/payment-callback-safety

---


# 支付回调安全规范

当系统涉及第三方支付回调（微信支付、支付宝等）或 webhook 通知时，防止伪造、篡改和重放攻击。

---

## 陷阱 #1: 回调未验证平台签名

**场景**: 收到支付回调后直接解密/解析并处理，未验证请求确实来自支付平台

### 问题根因

支付回调地址暴露在公网，任何人都可以伪造请求。如果不验签，攻击者可以构造假的"支付成功"通知。

### 错误示例

```java
// ❌ 错误: 直接解密处理，未验签
@PostMapping("/payment/callback/wechat")
public String wechatCallback(@RequestBody String body) {
    JsonNode json = objectMapper.readTree(body);
    // 直接尝试解密 resource
    String decrypted = decryptAesGcm(ciphertext, apiV3Key, nonce, aad);
    processPayment(decrypted);  // 谁发来的都处理
    return "{\"code\":\"SUCCESS\"}";
}
```

### 正确做法

```java
// ✅ 正确: 先验签，再解密，再处理
@PostMapping("/payment/callback/wechat")
public String wechatCallback(
    @RequestBody String body,
    @RequestHeader("Wechatpay-Signature") String signature,
    @RequestHeader("Wechatpay-Timestamp") String timestamp,
    @RequestHeader("Wechatpay-Nonce") String nonce,
    @RequestHeader("Wechatpay-Serial") String serial) {

    // 1. 用微信支付平台公钥验签（不是商户私钥）
    String message = timestamp + "\n" + nonce + "\n" + body + "\n";
    PublicKey platformKey = loadPlatformPublicKey(serial);
    if (!verifySignature(message, signature, platformKey)) {
        return "{\"code\":\"FAIL\",\"message\":\"验签失败\"}";
    }

    // 2. 验签通过后再解密和处理
    String decrypted = decryptAesGcm(ciphertext, apiV3Key, nonce, aad);
    processPayment(decrypted);
    return "{\"code\":\"SUCCESS\"}";
}
```

### 关键区分

| 密钥/证书 | 用途 | 持有方 |
|-----------|------|--------|
| 商户私钥 | 商户请求微信时签名 | 商户 |
| 商户 API 证书 | 商户身份标识 | 商户 |
| 微信支付平台公钥/证书 | 验证微信回调签名 | 微信平台签发，商户持有公钥 |
| API V3 Key | 解密回调通知体 | 商户 |

### 检查清单

- [ ] 回调入口是否在解密前先验证平台签名
- [ ] 验签使用的是平台公钥/证书，而非商户私钥
- [ ] 是否按 `Wechatpay-Serial` 匹配对应平台证书（支持证书轮换）
- [ ] 验签失败是否直接拒绝，不继续处理

---

## 陷阱 #2: 未做防重放校验

**场景**: 攻击者截获一份真实的支付成功回调，重复发送给系统

### 问题根因

合法的旧回调报文签名仍然有效，仅靠验签无法防止重放。

### 错误示例

```java
// ❌ 错误: 验签通过就直接处理，不检查是否重复
if (verifySignature(message, signature, platformKey)) {
    processPayment(decrypted);  // 同一笔单可能被处理多次
}
```

### 正确做法

```java
// ✅ 正确: 三层防重放
// 第 1 层: 时间戳窗口
long callbackTime = Long.parseLong(timestamp);
long now = Instant.now().getEpochSecond();
if (Math.abs(now - callbackTime) > 300) {  // 5 分钟窗口
    return "{\"code\":\"FAIL\",\"message\":\"timestamp expired\"}";
}

// 第 2 层: 按 transaction_id 幂等
String transactionId = payData.get("transaction_id").asText();
if (paymentRecordRepository.existsByTransactionIdAndStatus(
        transactionId, "SUCCESS")) {
    log.info("重复通知，已处理: transactionId={}", transactionId);
    return "{\"code\":\"SUCCESS\"}";  // 返回成功，让平台停止重试
}

// 第 3 层: 订单状态机幂等
TradeOrder order = orderRepository.findByOrderNumber(outTradeNo);
if (order.getPaymentStatus() == PaymentStatus.PAID) {
    log.info("订单已支付，跳过: orderId={}", order.getId());
    return "{\"code\":\"SUCCESS\"}";
}
```

### 检查清单

- [ ] 是否校验回调时间戳窗口（建议 5 分钟）
- [ ] 是否按 transaction_id 做幂等判重
- [ ] 是否检查订单当前状态（防止已支付订单被重复处理）
- [ ] 重复通知是否返回成功（让平台停止重试）

---

## 陷阱 #3: 信任回调中的金额

**场景**: 直接使用回调报文中的金额作为入账依据，未与本地订单金额校验

### 问题根因

即使验签通过，也应以本地订单金额为准做一致性校验，防止订单错配或极端情况下的金额不一致。

### 错误示例

```java
// ❌ 错误: 直接用回调金额入账
int paidAmount = payData.get("amount").get("total").asInt();
order.setPaidAmount(paidAmount);  // 不校验是否与下单金额一致
order.setStatus("PAID");
```

### 正确做法

```java
// ✅ 正确: 回调金额必须与本地订单金额严格一致
int callbackAmountFen = payData.get("amount").get("total").asInt();
int expectedAmountFen = order.getTotalAmount()
    .multiply(BigDecimal.valueOf(100)).intValue();

if (callbackAmountFen != expectedAmountFen) {
    log.error("金额不一致: callback={}, expected={}, orderId={}",
        callbackAmountFen, expectedAmountFen, order.getId());
    // 标记异常，不入账
    paymentRecord.setReconcileStatus("MISMATCHED");
    paymentRecord.setReconcileErrorMessage("金额不一致");
    return;
}
```

### 检查清单

- [ ] 回调金额是否与本地订单应付金额做了严格比对
- [ ] 金额比对的口径是否与下单请求一致（同一个字段）
- [ ] 金额不一致时是否拒绝入账并记录异常
- [ ] 是否有封装方法明确"微信支付金额口径"（防止后续改动导致口径分叉）

---

## 陷阱 #4: 回调与对账走不同的校验逻辑

**场景**: 回调链路有完整校验，但"手动对账"链路跳过了部分校验

### 问题根因

对账补单和回调处理本质上都是"确认支付成功"，如果走不同的校验逻辑，容易在对账链路留下安全缺口。

### 错误示例

```java
// ❌ 错误: 回调有完整校验
public void handleCallback(JsonNode payData, TradeOrder order) {
    validateAmount(payData, order);
    validateMchId(payData, config);
    validateAppId(payData, config);
    processPayment(order, transactionId);
}

// ❌ 错误: 对账直接补单，跳过校验
public void reconcile(PaymentRecord record) {
    JsonNode queryResult = queryWechatOrder(outTradeNo);
    if ("SUCCESS".equals(tradeState)) {
        processPayment(order, transactionId);  // 没有校验金额/商户号
    }
}
```

### 正确做法

```java
// ✅ 正确: 抽取统一校验函数，回调和对账都复用
public void validatePaymentResult(
    JsonNode payData, TradeOrder order, TenantConfig config) {
    // 1. out_trade_no 一致
    // 2. transaction_id 非空
    // 3. appid 一致
    // 4. mchid 一致
    // 5. 金额一致
    // 任何一项不通过都抛异常
}

// 回调链路
public void handleCallback(JsonNode payData, TradeOrder order, TenantConfig config) {
    validatePaymentResult(payData, order, config);
    processPayment(order, transactionId);
}

// 对账链路
public void reconcile(PaymentRecord record) {
    JsonNode queryResult = queryWechatOrder(outTradeNo);
    validatePaymentResult(queryResult, order, config);  // 同一套校验
    processPayment(order, transactionId);
}
```

### 检查清单

- [ ] 回调和对账是否复用同一套支付结果校验逻辑
- [ ] 对账补单是否也校验了金额、商户号、AppID
- [ ] "人工点击对账按钮"本身是否不算支付成功依据
- [ ] 对账是否只信任支付平台订单查询 API 的真实返回

---

## 陷阱 #5: 占位/TODO 实现上线

**场景**: 支付查询、对账等关键逻辑使用占位实现，但未被发现就上线了

### 错误示例

```java
// ❌ 错误: 占位实现，返回假数据
private JsonNode queryWechatOrderStatus(PaymentRecord record) {
    // TODO: 接入微信支付订单查询 V3 API
    log.warn("微信订单查询 API 待实现: orderId={}", record.getOrderId());
    return objectMapper.createObjectNode()
        .put("trade_state", "NOTPAY")
        .put("trade_state_desc", "未支付(占位)");
}
```

### 正确做法

```java
// ✅ 正确: 占位实现必须明确失败，不能返回看似正常的假数据
private JsonNode queryWechatOrderStatus(PaymentRecord record) {
    throw new UnsupportedOperationException(
        "微信订单查询 API 未实现，请先完成接入");
}
```

### 检查清单

- [ ] 支付相关的 TODO/占位实现是否会抛异常而非返回假数据
- [ ] 是否有日志或监控能发现占位逻辑被触发
- [ ] 上线前是否检查了支付链路中的所有 TODO

---

## 检查清单（支付回调安全）

**验签与防伪**:
- [ ] 回调是否验证了平台签名
- [ ] 验签使用的是平台公钥/证书（非商户私钥）
- [ ] 是否支持平台证书轮换（按 serial 匹配）

**防重放**:
- [ ] 是否校验时间戳窗口
- [ ] 是否按 transaction_id 做幂等
- [ ] 是否检查订单状态机

**业务校验**:
- [ ] 金额是否与本地订单严格一致
- [ ] out_trade_no 是否与本地订单号一致
- [ ] appid / mchid 是否与租户配置一致
- [ ] 回调与对账是否复用同一套校验

**实现完整性**:
- [ ] 支付链路是否有占位/TODO 实现
- [ ] 占位实现是否会明确失败（而非返回假数据）

---

## 适用范围

- 微信支付 API v3
- 支付宝开放平台
- Stripe Webhooks
- PayPal IPN/Webhooks
- 其他第三方支付/webhook 通知

---

## 规则溯源

```
> 📋 本回复遵循：`payment-callback-safety` - [章节名]
```