# Coinbase企业退款：核对部分退款、幂等与事件回执

整理：链小知（AI 辅助）
资料核对日期：2026-10-14
引用地址：https://lianxiaozhi.com/tools/guides/coinbase-payment-refund-idempotency-receipt-check
难度：进阶
核验方式：官方文档整理，未执行真实账户操作

核既有退款输入和异步结果，防止超时后把重复提交当新退款。

## 使用工具
- [Coinbase Payment Acceptance](https://lianxiaozhi.com/tools/coinbase-payment-acceptance) · [官方入口](https://docs.cdp.coinbase.com/payments/payment-acceptance/overview)

## 前置条件
- 准备已有且脱敏的订单、请求或回执记录；没有实际记录时仅按文档列出待核字段。
- 本教程依据公开资料，不登录、申请密钥、调用业务API、创建收款或执行退款。

## 1. 先核可退余额和退款输入

对已有请求核POST /v2/payment-sessions/{paymentSessionId}/refunds，前提为refundable大于零且refundExpiresAt未过。CreateRefundRequest要求source，指向退款资金来源的CDP账户或链上地址。

amount按会话asset的十进制金额解释；省略会退全部剩余可退额，允许多次部分退款。核reason、externalReferenceId及对应订单，金额未知时不拟定或发送退款。

核对结果：资金来源、金额是否省略、可退余额及期限都已核对。
依据：[Coinbase v2：退款输入、异步结果与幂等参数](https://docs.cdp.coinbase.com/api-reference/v2/rest-api/payment-sessions/refund-a-payment-session.md)
依据：[Coinbase Payment Sessions：余额、到期和关联记录](https://docs.cdp.coinbase.com/payments/payment-acceptance/payment-sessions.md)

## 2. 把业务退款号和幂等键分开

该退款接口明确引用X-Idempotency-Key。核已有同一请求使用相同UUID v4键；文档24小时窗口内同参数重复返回首次响应，同键异参数产生idempotency_error。

externalReferenceId用于商户对账，不替代幂等键。超时或already_exists提示仍在处理时，保留原请求与响应；换键意味着新请求，不能用来猜测原退款失败。

核对结果：原请求参数、UUID v4键与退款业务号分列；无结果不自动另发。
依据：[Coinbase v2：退款输入、异步结果与幂等参数](https://docs.cdp.coinbase.com/api-reference/v2/rest-api/payment-sessions/refund-a-payment-session.md)
依据：[Coinbase v2：24小时幂等、UUID及冲突](https://docs.cdp.coinbase.com/api-reference/v2/idempotency.md)

## 3. 按退款ID查异步结果

退款创建成功返回pending，并非已到账。核已有refundId与paymentSessionId，用GET /v2/payment-sessions/{paymentSessionId}/refunds/{refundId}的记录比较status、amount、reason、updatedAt和onchainTransactions。

succeeded或failed属于单次退款结果；多次部分退款须再对照会话refunded/refundable及各refundId。404、权限不足或服务失败只保留未知，不填退款完成。

核对结果：退款ID、单次结果和累计退款余额一致或留下差异。
依据：[Coinbase v2：退款输入、异步结果与幂等参数](https://docs.cdp.coinbase.com/api-reference/v2/rest-api/payment-sessions/refund-a-payment-session.md)
依据：[Coinbase v2：查询单笔退款](https://docs.cdp.coinbase.com/api-reference/v2/rest-api/payment-sessions/get-a-payment-session-refund.md)
依据：[Coinbase Payment Sessions：余额、到期和关联记录](https://docs.cdp.coinbase.com/payments/payment-acceptance/payment-sessions.md)

## 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及验签结果已对应；无验签记录不视为可信完成通知。
依据：[Coinbase Payment Acceptance：事件信封与重复处理](https://docs.cdp.coinbase.com/webhooks/payment-acceptance/overview.md)
依据：[Coinbase Payment Acceptance：签名与五分钟重放边界](https://docs.cdp.coinbase.com/webhooks/payment-acceptance/verification.md)

## 常见错误
- 24小时幂等不是无限期防重复保证，重复请求仍计入限流。
- pending、页面提示和HTTP创建成功不能替代最终退款回执。

## 完成检查
- 形成订单、资源ID、金额、状态与未验证项的对照；保留失败原文。

## 相关知识

## 官方依据
- [Coinbase v2：退款输入、异步结果与幂等参数](https://docs.cdp.coinbase.com/api-reference/v2/rest-api/payment-sessions/refund-a-payment-session.md)
- [Coinbase Payment Sessions：余额、到期和关联记录](https://docs.cdp.coinbase.com/payments/payment-acceptance/payment-sessions.md)
- [Coinbase v2：24小时幂等、UUID及冲突](https://docs.cdp.coinbase.com/api-reference/v2/idempotency.md)
- [Coinbase v2：查询单笔退款](https://docs.cdp.coinbase.com/api-reference/v2/rest-api/payment-sessions/get-a-payment-session-refund.md)
- [Coinbase Payment Acceptance：事件信封与重复处理](https://docs.cdp.coinbase.com/webhooks/payment-acceptance/overview.md)
- [Coinbase Payment Acceptance：签名与五分钟重放边界](https://docs.cdp.coinbase.com/webhooks/payment-acceptance/verification.md)