USDC 收银台集成

标准 API 形态

USDC 收单 API 大体沿用了 Stripe 推广开来的支付意图模式。最基本的接口包括：

1. 1

   服务器创建支付意图

   调用 POST /v1/payments，请求体包含 amount、currency（以法币报价时为 USD；以稳定币报价时为 USDC）、settlement_preference（USDC 或法币）、networks（允许的网络列表）、order_id（您的幂等键）、success_url、cancel_url，以及一个供您自行对账使用的 metadata 数据块。

2. 2

   收单机构返回收银台 URL 或组件配置

   托管收银台：返回一个 URL，买家会被重定向到该地址。嵌入式组件：返回一份客户端配置（可公开密钥、支付意图 ID），由组件加载。两种流程都会处理钱包检测、网络选择和报价展示。

3. 3

   买家在钱包中签名，链上转账广播

   移动端：通过深度链接跳转到 MetaMask、Phantom、Trust 等钱包。桌面端：使用 WalletConnect 二维码或浏览器扩展弹窗。买家核对金额后签名。

4. 4

   收单机构等待区块确认，触发 Webhook

   收单机构向您发送 POST your_webhook_url 请求，载荷包含 event_type: “payment.succeeded”、order_id、amount、tx_hash、network，以及一个您需要用收单机构的 Webhook 密钥验证的签名。

5. 5

   服务器以幂等方式将订单标记为已付款

   验证 Webhook 签名，在数据库中查询 (order_id, tx_hash)，如尚未标记则标记为已付款，然后发起履约。

网络选择

接受哪些网络，是用户体验与成本之间的权衡：

• Solana：网络费用不到一美分，确认时间不到一秒。是小额客单价（AOV）场景的最佳默认选择。
• Base：网络费用几美分，确认需要几秒。钱包支持广泛；对加密原生用户群来说是不错的默认选择。
• Polygon、Arbitrum：费用和速度与 Base 相近。可以加入，但并非必需。
• Ethereum 主网：视 Gas 情况，网络费用为 $1–$8+。对小额订单的买家来说负担较重。适合高客单价（超过 $500）订单，或作为备选。
• Tron：如果您面向亚洲和非洲的 USDT 资金流，值得考虑在 USDC 之外同时支持 TRON 上的 USDT。

Webhook 幂等性

Webhook 会重试，因此您的处理程序必须具备幂等性。标准模式如下：

1. 使用收单机构的密钥，通过 HMAC-SHA256 验证 Webhook 签名。
2. 从载荷中提取 (order_id, tx_hash)。
3. 在您的 processed_payments 表中查询这一组合。
4. 如果找到：直接返回 200 OK，不做任何其他操作。
5. 如果未找到：插入该行（对这一组合设置 UNIQUE 约束），然后在主订单表中将订单标记为已付款，再发起履约。
6. 将第 5 步包在同一个数据库事务中，这样即使流程中途崩溃，也不会重复履约。

大多数收单 Webhook 都包含一个投递 ID，请记录下来以便调试，但不要把它当作幂等键。网络确认和收单机构的重试可能产生多个重复的 payment.succeeded 事件，它们的投递 ID 不同，tx_hash 却相同；去重必须基于链上身份，而不是投递记录。

退款流程

主流的模式有两种：

• 原路退款：收单机构将 USDC 退回买家最初付款所用的地址。用户体验最简洁；之所以可行，是因为链上付款记录中包含来源地址。
• 退款至指定地址：由买家指定退款目的地（如果买家是从交易所或热钱包付款，该地址可能与来源地址不同）。大多数收单机构通过带有 destination_address 的 POST /v1/refunds 支持这一方式。

退款这一环节的网络费用由商户承担。全额退款和部分退款均受支持。退款本身所需的链上确认时间与原始付款相同。

生产环境中的故障情形

• 买家签名后放弃。链上转账已经广播，但买家在 Webhook 触发之前关闭了页面。收单机构仍会通过链上监控检测并确认这笔付款；您的履约流程应由 Webhook 触发，而不是由页面重定向触发。
• 买家支付的金额不对。大多数收单机构会在链上检测时拒绝金额不符的付款。部分收单机构允许近似匹配（在一定容差范围内），并在 Webhook 中标明差额。
• 买家在错误的网络上付款。如果买家在 Ethereum 上签名，而您只接受 Solana，这笔付款将完全不在收单机构的监控范围内。大多数服务商会通过找回流程退还资金；有些则会导致资金丢失。请在结账时清楚标明网络选择。
• 买家从交易所地址付款。原路退款可能被退回，或进入错误的账户。对于任何可能产生退款的产品，请在结账时明确收集退款目的地址。
• 稳定币脱锚。虽然罕见，但确实会发生。如果 USDC 在报价与链上结算之间的短暂窗口内大幅脱锚，差额将视双方协议由商户或收单机构承担。