EasyPost 并不通过 return_update 状态通知运费退款完成，而是专门触发 refund.successful 类型的 Webhook 事件；该事件在 carrier（如 USPS）实际完成退款后异步发出，通常延迟数日甚至数周，且无法在测试环境中模拟。
easypost 并不通过 `return_update` 状态通知运费退款完成，而是专门触发 `refund.successful` 类型的 webhook 事件；该事件在 carrier（如 usps）实际完成退款后异步发出，通常延迟数日甚至数周，且无法在测试环境中模拟。
在 EasyPost 的事件体系中，refund.successful 是唯一用于标识运费退款已被承运商正式接受并完成结算的 Webhook 事件类型。这与常见的物流状态更新（如 status_update、out_for_delivery）有本质区别：它不反映包裹轨迹，而是代表财务动作的最终确认。
✅ 正确监听方式
你需要在 Webhook 接收端显式检查 event.type 字段（而非 result.statusDetail），示例如下：
Temu欧洲站-退货退款
下载
Temu 欧洲站电商退货退款API，通过 LinkFox 网关转发 Partner EU Returns & Refunds / 售后退货退款 相关后台/Temu 接口（退货申请、退款、售后单查询与处理等），接口将按 Partner 文档逐条接入。当用户提到 Temu EU 退货、退款、售后退货、return...
// 假设 result 是解析后的 JSON Webhook payload（顶层对象）
String eventType = (String) result.get("event_type"); // 注意：EasyPost v3+ 使用 event_type 字段
if ("refund.successful".equals(eventType)) {
Map<String, Object> eventData = (Map<String, Object>) result.get("data");
Map<String, Object> refundData = (Map<String, Object>) eventData.get("object");
String refundId = (String) refundData.get("id");
String shipmentId = (String) refundData.get("shipment_id");
BigDecimal amount = new BigDecimal((String) refundData.get("amount"));
String carrier = (String) refundData.get("carrier");
String status = (String) refundData.get("status"); // 通常为 "submitted" 或 "succeeded"
// 关联本地订单并执行退款逻辑
Shipment userShipment = shipmentService.retrieveShipmentFromEasypostId(shipmentId);
if (userShipment != null && "succeeded".equals(status)) {
try {
Refund stripeRefund = stripeService.refund(userShipment.getStripeChargeId(), amount.doubleValue());
userShipment.setStripeRefundId(stripeRefund.getId());
userShipment.setStatus(ShipmentStatus.REFUND_PROCESSED);
userShipment.setEasypostStatus(EasypostShipmentStatus.REFUNDED);
shipmentService.updateShipment(userShipment);
activityLoggerService.insert(
userShipment.getUser(),
userShipment,
activityLoggerService.getShipmentRefundProcessed(userShipment, amount.doubleValue()),
ActivityMessageType.REFUND_PROCESSED
);
} catch (StripeException e) {
log.error("Failed to issue Stripe refund for EasyPost refund {}", refundId, e);
}
}
}⚠️ 关键注意事项
- statusDetail 字段不适用于退款事件：你当前代码中依赖 statusDetail.equals("return_update") 是无效的——EasyPost 的 return_update 仅用于退货包裹轨迹（如 return_received），与运费退款无关。
- 事件延迟不可忽略：USPS 退款平均需 15–30 天才触发 refund.successful；FedEx/UPS 通常更快（1–7 天），但均属异步行为，绝不可依赖“提交退款请求”即视为成功。
- 测试环境限制：EasyPost 的 test 模式不会生成真实的 refund.successful Webhook，即使调用 Refund.create(...) 测试方法。生产环境验证前，建议使用 live key + 小额真实标签进行端到端测试。
- 幂等性必须保障：因网络重试或事件重复投递，同一 refund.successful 事件可能多次到达，请基于 refund.id 做去重处理（如数据库唯一索引或 Redis Set 记录已处理 ID）。
? 总结
将退款状态同步逻辑从物流状态分支（statusDetail）彻底剥离，单独构建 refund.successful 事件处理器，是确保财务一致性与系统健壮性的关键。务必以 event_type 为判断依据，结合 carrier 实际结算周期设计超时监控与人工兜底流程。
