在加密货币支付领域，及时准确地掌握交易状态至关重要。Coinbase Commerce 作为专业的支付处理工具，通过两套核心机制来监控和确认支付：Charge API 和 Webhook 事件。本文将深入解析这两种机制的工作原理、状态含义以及最佳实践，助你高效管理加密货币收款。
Charge API：状态时间线追踪
每当创建一个支付请求（charge）后，Commerce 系统便会开始在区块链上监控与该 charge 相关的所有转入交易。其状态演进被完整记录在 Charge API 模型的 timeline 字段中。
该字段是一个状态对象数组，每个对象都包含一个状态值（status）和对应的时间戳（timestamp），清晰展示了一次 charge 的完整生命周期。
主要状态及其含义
- NEW（新建）
charge 已被成功创建，但尚未发生任何进一步的行动。这是支付的起点。 - SIGNED（已签名）
交易已被钱包所有者签名，资金准备就绪，等待发送。这表示付款方已确认支付。 - PENDING（待确认）
交易已被区块链网络检测到，资金已到达商户钱包。这是资金已到账但尚未最终确认的关键阶段。 - COMPLETED（已完成）
交易已最终确定，并受到保护，可免受分叉或链重组的影响。此时支付已百分百安全。
timeline 数组中的最后一条记录，即为该 charge 的当前状态。
Webhook 事件：实时推送通知
除了主动查询 API，Commerce 系统还会通过 Webhook 事件向您的服务器发送实时状态更新。每种事件类型都对应支付流程中的一个特定阶段。
核心事件类型
- charge:created
一个新的 charge 已被初始化。这意味着客户已发起支付，并看到了收款地址。 - charge:pending
charge 对应的交易已被发布到区块链上，且资金已被商户接收。这与 API 中的 PENDING 状态相对应。 - charge:confirmed
charge 已得到完全确认，支付被视为最终完成。这与 API 中的 COMPLETED 状态等价。 - charge:failed
charge 未能完成。这可能是由于网络拥堵、手续费不足或付款方取消等原因造成。
机制对比：如何选择？
- Charge API 通过其时间线数组提供了每一笔交易的详细历史记录。它非常适合需要进行连续状态追踪的后端集成，您可以在需要时主动查询以获取最新状态。
- Webhook 则直接将实时通知推送到您的服务器。这非常适合需要立即触发的操作，例如当支付达到“PENDING”状态时自动履行订单，无需轮询查询。
两种方式相辅相成，您可以根据业务逻辑的实时性要求选择使用，或结合两者以实现最可靠的支付处理流程。👉 查看实时支付状态管理工具
深入理解关键支付状态
PENDING（待确认状态）
该状态在两种机制中都扮演着至关重要的角色。它意味着交易已被纳入一个区块链区块中，标志着资金已成功转移并进入确认流程。
一个 charge 通常会在购买后的 2-10 秒内转变为 PENDING 状态。交易在到达此状态后失败的概率极低——小于百万分之一。鉴于这种极高的可靠性，商户完全可以放心地选择在订单处于 PENDING 状态时就交付商品或服务。这能极大提升客户体验。
COMPLETED/CONFIRMED（已完成/已确认状态）
此状态意味着支付已最终确定，并安全地受到了保护，足以抵御任何区块链重组的风险。交易通常会在约 15 分钟内从 PENDING 状态过渡到 COMPLETED/CONFIRMED 状态。
状态选择策略：效率与终局性
为了提升运营效率和客户满意度，您可以使用 PENDING 状态来加速订单履行。这在保证极高交易安全性的同时，实现了近乎实时的交付。
如果您更看重资金的绝对终局性而非速度，则可以选择等待交易达到 COMPLETED/CONFIRMED 状态后再行发货。这完全取决于您的业务模式和风险偏好。
常见问题
Q1: PENDING 状态和 COMPLETED 状态最大的区别是什么？
A: 最核心的区别在于交易的“最终性”。PENDING 状态表示交易已打包上链且资金到账，安全性极高；而 COMPLETED 状态则表示交易已经过足够多的确认，能够抵抗区块链回滚风险，达到了绝对最终性。
Q2: 我应该依赖 Charge API 还是 Webhook 来更新我的订单系统？
A: 推荐以 Webhook 作为主要驱动方式，因为它能提供最及时的推送通知。同时，可以将 Charge API 作为备用方案或对账工具，在需要主动查询或验证状态时使用。
Q3: 遇到 charge:failed 事件通常是什么原因？
A: 支付失败可能源于多种情况，例如网络拥堵导致交易未被收录、付款方设置的手续费过低，或是付款方在签名后最终取消了交易。
Q4: 从 PENDING 到 COMPLETED 通常需要多久？
A: 这个过程通常需要大约 15 分钟。具体时间会因不同区块链网络的出块速度和确认要求而略有差异。
Q5: 在 PENDING 状态发货真的安全吗？
A: 是的，基于 Coinbase Commerce 的数据，交易在进入 PENDING 状态后失败的概率极低（小于百万分之一）。对于绝大多数电商场景而言，在此状态发货是安全且能极大提升用户体验的最佳实践。
Q6: 如何集成这些支付状态到我的网站？
A: 您需要在后端服务器上设置相应的 Webhook 端点来接收事件通知，并编写处理逻辑（如更新数据库订单状态）。同时，前端可以调用 Charge API 来向用户展示支付时间线。👉 获取进阶集成方法与代码示例