Coinbase企业退款：核对部分退款、幂等与事件回执
链小知 · 进阶 · 核验 · 依官方文档整理
核既有退款输入和异步结果，防止超时后把重复提交当新退款。
开始前准备
- 准备已有且脱敏的订单、请求或回执记录；没有实际记录时仅按文档列出待核字段。
- 本教程依据公开资料，不登录、申请密钥、调用业务API、创建收款或执行退款。
1. 先核可退余额和退款输入
对已有请求核POST /v2/payment-sessions/{paymentSessionId}/refunds，前提为refundable大于零且refundExpiresAt未过。CreateRefundRequest要求source，指向退款资金来源的CDP账户或链上地址。
amount按会话asset的十进制金额解释；省略会退全部剩余可退额，允许多次部分退款。核reason、externalReferenceId及对应订单，金额未知时不拟定或发送退款。
检查结果：资金来源、金额是否省略、可退余额及期限都已核对。
2. 把业务退款号和幂等键分开
该退款接口明确引用X-Idempotency-Key。核已有同一请求使用相同UUID v4键；文档24小时窗口内同参数重复返回首次响应，同键异参数产生idempotency_error。
externalReferenceId用于商户对账，不替代幂等键。超时或already_exists提示仍在处理时，保留原请求与响应；换键意味着新请求，不能用来猜测原退款失败。
检查结果：原请求参数、UUID v4键与退款业务号分列；无结果不自动另发。
3. 按退款ID查异步结果
退款创建成功返回pending，并非已到账。核已有refundId与paymentSessionId，用GET /v2/payment-sessions/{paymentSessionId}/refunds/{refundId}的记录比较status、amount、reason、updatedAt和onchainTransactions。
succeeded或failed属于单次退款结果；多次部分退款须再对照会话refunded/refundable及各refundId。404、权限不足或服务失败只保留未知，不填退款完成。
检查结果：退款ID、单次结果和累计退款余额一致或留下差异。
4. 核事件真实性并去重
Payment Acceptance事件包含eventId、eventType、timestamp；动作事件还带data.refund及data.paymentSession。按eventId去重，核refund_pending、refund_succeeded或refund_failed属于同一退款。
接收方需按X-Hook0-Signature提取t、h、v1，以时间戳、签名头名/头值及原正文构造签名载荷，再用订阅secret做HMAC-SHA256、恒定时间比较，拒绝超过五分钟的旧事件。不要套用其他平台的单独正文签名算法；本文仅核文档与已有脱敏验签结果。
检查结果：事件ID、退款ID及验签结果已对应；无验签记录不视为可信完成通知。
怎样确认完成
- 形成订单、资源ID、金额、状态与未验证项的对照；保留失败原文。
常见错误与边界
- 24小时幂等不是无限期防重复保证，重复请求仍计入限流。
- pending、页面提示和HTTP创建成功不能替代最终退款回执。