如何不用真钱测试加密货币支付：沙盒、测试网与水龙头

加密货币支付测试不能只证明“钱包显示了交易哈希”。你的应用还要创建正确的订单、展示链与资产明确的精确付款指令、检测转账、等待确认与最终完成、接收异步 Webhook，并确保每项业务副作用只执行一次。如果全部使用主网测试，每个错误都会损失真钱；如果全部替换成模拟数据，又会掩盖最需要发现的接入故障。

实用的解决方法是把测试分成三层：

1. 用本地测试验证验签、事件去重、过期处理和状态顺序等确定性规则；
2. 用沙盒环境与公共测试网验证真实的钱包、远程过程调用节点、扫描器、确认与 Webhook 链路；
3. 上线前核对沙盒与生产环境的边界，不要用一笔小额真实转账代替缺失的测试。

最短的端到端路径，是在 StableOps 试验场使用 Base Sepolia USDC。测试网 USDC 没有真实金融价值，但钱包交易以及订单从 created 到 finalized 的生命周期都真实发生在测试网上。

为什么加密货币支付需要三层测试

链上支付有三个特点，使它不同于普通的同步接口测试。

不要让一个缓慢的浏览器测试同时承担三类职责。合理的测试套件应包含大量快速本地测试、少量真实测试网流程，以及启用生产环境前的一份简短配置核对表。

每一层应该证明什么

第一层：确定性的本地测试

业务正确性不应依赖水龙头或公共远程过程调用节点。本地单元测试和集成测试至少要证明应用能够：

• 使用未经修改的原始请求正文验签；
• 拒绝缺少签名、签名过期或签名错误的请求；
• 依靠数据库唯一约束写入 X-Event-Id；
• 同一事件到达两次时，只接受一次状态变化、只履约一次；
• 较旧事件迟到时，不会让业务状态倒退；
• 只允许 payment.finalized 触发不可逆履约；
• 把 payment.expired 与 payment.reverted 分别送入明确的异常分支；
• 使用相同幂等键重试建单时，不会产生第二笔业务债权。

这一层应使用模拟时钟。你可以在几毫秒内把订单时间推进到过期，也可以随时使用带有效签名的 payment.reverted 测试数据。公共测试网很难快速、稳定地复现这些情况，因此它们更适合留在本地测试中。

第二层：运行在真实测试网上的沙盒环境

沙盒测试应该验证本地代码无法覆盖的接缝：

• 所选钱包能切换到预期测试网；
• 代币合约或铸币地址确实是 StableOps 在该网络上支持的资产；
• 钱包把返回的 order.amount 精确发送到客户所选付款指令的地址；
• 链扫描器能发现并匹配这笔转账；
• 无需人工推送状态，订单便能依次进入 detected、confirmed 与 finalized；
• 带签名的 Webhook 投递能到达公开的测试端点。

StableOps 会按组织、环境、链、地址、资产以及最小单位精确金额隔离扫描和匹配。因此，沙盒订单使用没有价值的测试资产，却能覆盖与生产环境相同的支付语义。

第三层：上线前的边界核对

不要把主网当成缺失的一层测试。最后一步应该核对生产环境中有意不同的配置：接口密钥、收款地址、Webhook 端点与密钥、开放链、监控方式和运营责任人。代码路径在此之前就应通过前两层测试。

最短端到端测试：Base Sepolia USDC

你需要一枚 StableOps 沙盒接口密钥、一个以太坊虚拟机浏览器钱包，以及一个与真实资金隔离的测试钱包地址。开发过程不要复用资金钱包。

1. 给测试钱包领取资产

在 Base Sepolia 上领取两种测试资产：

• 用于支付金额的测试网 USDC；
• 用于支付燃料费的 Base Sepolia ETH。

两项余额必须位于同一个测试网。主网 ETH 不能支付 Base Sepolia 燃料费，主网 USDC 更不能发送到试验场给出的付款指令。水龙头可用性和领取限制经常变化，因此应使用持续维护的测试网 USDC 与 USDT 水龙头清单，不要从旧教程复制外部链接。Circle 明确说明测试网 USDC 没有金融价值；即便如此，签名与授权仍然是真实操作，所以钱包仍应保持隔离。

2. 在试验场创建沙盒订单

打开试验场，粘贴以 sk_sandbox_… 开头的密钥。如果沙盒地址池为空，保持“自动导入沙盒收款地址”开启。选择 Base Sepolia · USDC，输入一个小额金额并创建订单。

付款前先记录以下返回值：

试验场可能为这次沙盒演示导入一个确定性销毁地址。没有人持有其私钥，所以发送到该地址的测试币会有意变得无法取回。对没有价值的水龙头代币而言这不构成损失，也再次说明绝不能通过试验场发送主网资产。

3. 让钱包发送精确付款

连接测试钱包，让试验场提交 USDC 转账。签名前在钱包确认页逐项核对：

• 网络：Base Sepolia；
• 资产：受支持的 Base Sepolia USDC 合约；
• 收款人：订单返回的付款指令地址；
• 金额：返回的 order.amount，而不是你记忆中刚才输入的数字。

交易哈希只表示钱包已经广播交易。它是有用的排查证据，但不是履约凭据。

4. 观察生命周期到达最终完成

试验场会轮询订单并展示每次状态变化：

created -> detected -> confirmed -> finalized

detected 表示扫描器已经匹配一笔链上转账；confirmed 表示已经达到该链的确认阈值；finalized 表示 StableOps 已达到配置的最终确认深度，也是生产环境触发不可逆履约的推荐时机。测试网出块与公共远程过程调用节点建立索引的速度会波动，因此测试应断言状态顺序和一个宽裕的超时时间，不能断言固定秒数。

如果需要独立核对终态，可以在建单后运行下面的脚本。它使用当前接口软件开发工具包，并会在订单过期、取消、回滚或等待超时时以失败状态退出：

import { StableOps } from '@stableops/api-sdk'

const apiKey = process.env.STABLEOPS_API_KEY
const paymentOrderId = process.argv[2]

if (!apiKey?.startsWith('sk_sandbox_')) {
  throw new Error('请使用沙盒接口密钥')
}
if (!paymentOrderId) throw new Error('请传入支付订单号')

const client = new StableOps({ apiKey })
const deadline = Date.now() + 10 * 60 * 1000
let previousStatus: string | undefined

while (Date.now() < deadline) {
  const order = await client.paymentOrders.retrieve(paymentOrderId)

  if (order.status !== previousStatus) {
    console.log(new Date().toISOString(), order.status)
    previousStatus = order.status
  }

  if (order.status === 'finalized') process.exit(0)
  if (['reverted', 'expired', 'canceled'].includes(order.status)) {
    throw new Error(`订单终态为 ${order.status}`)
  }

  await new Promise((resolve) => setTimeout(resolve, 3_000))
}

throw new Error('等待最终完成超时')

将其保存为 wait-for-payment.ts，安装 @stableops/api-sdk 与 tsx 后运行：

STABLEOPS_API_KEY=sk_sandbox_... npx tsx wait-for-payment.ts po_...

轮询适合用作测试断言与恢复路径。实际应用仍应使用带签名的 Webhook 获取低延迟事件流。

单独测试 Webhook 路径

把沙盒 Webhook 端点指向一个公开的 HTTPS 测试地址，订阅 payment.detected、payment.confirmed、payment.finalized、payment.reverted 与 payment.expired，然后完整执行一次试验场流程。

每次投递都应保留：

• 用于验签的原始请求正文；
• 作为事件级去重键的 X-Event-Id；
• 作为单次投递诊断键的 X-Delivery-Id；
• 事件类型、支付订单号、响应码和处理结果。

处理器成功接收事件后，再重放一次相同投递。第二次请求仍应返回成功响应，但不得再次履约或写入账目。另外，本地还要用不同顺序输入同一组事件测试数据。真实网络不会保证每个消费者都按照自己期望的顺序观察到全部异步结果。

完整的持久事件收件箱与发件箱模式，见稳定币支付 Webhook：如何避免重复履约。

可直接复制的加密货币支付测试矩阵

可以把下表作为最小发布测试集。只有真实测试网能提供额外信息时，才让用例依赖测试网；其余用例都应保持确定性。

不要试图操纵公共测试网来制造链重组，也不要调用不存在的“设置订单状态”接口。StableOps 不提供人工推送订单状态的路径：回滚分支用测试数据验证，正常链驱动生命周期则交给测试网验证。

让沙盒与生产环境不可能混淆

环境隔离应该单独设置发布门槛，因为一段正确的测试如果使用了错误凭据，仍可能移动真实资金。

• 持续集成、预览部署、本地终端和浏览器演示只包含 sk_sandbox_… 密钥。
• 除明确命名的生产部署外，应用启动时拒绝 sk_live_… 密钥。
• 沙盒与生产环境使用不同的 Webhook 端点，或使用明确隔离的事件收件箱命名空间和密钥。
• 测试网收款地址只配置在沙盒环境，主网收款地址只配置在生产环境。
• 日志与对账记录包含环境、组织、merchantOrderId 和支付订单号。
• 测试数据不包含真实客户资料、私钥、助记词或生产 Webhook 密钥。
• 第一笔客户付款前，生产监控已经覆盖投递失败、死信、订单过期与地址池容量。
• 上线核对使用当前文档验证支持的链与代币合约，绝不复制测试网值。

环境由接口密钥本身决定；不存在把沙盒密钥变成生产密钥的请求头。应该把上线视为使用生产凭据重新创建经过核对的配置，而不是把沙盒订单迁移到生产环境。

常见问题

没有任何测试网代币，也能测试加密货币支付吗？

验签、幂等、Webhook 顺序、过期逻辑和回滚处理都可以只用本地测试数据。要执行真实的钱包到扫描器端到端测试，仍需要测试网稳定币和该网络的原生燃料代币。两者都能通过水龙头领取，且没有金融价值。

加密货币支付沙盒只是模拟区块链吗？

StableOps 试验场不是这样。建单使用沙盒凭据，但钱包会在公共测试网上广播真实转账；扫描、匹配、确认观察和最终完成都走真实链路，所以远程过程调用延迟和出块时间会波动。

应该如何测试链重组与 payment.reverted？

在本地集成测试中使用带签名的事件测试数据触发回滚路径，并验证 payment.finalized 之前绝不启动不可逆履约。链重组非常少见，也无法在公共测试网上安全控制，因此等待真实重组不是可行的发布测试。生命周期边界见稳定币支付确认数。

先跑通一笔，再自动验证边界

从试验场开始，使用持续维护的水龙头清单给隔离钱包领取测试资产，并观察一笔 Base Sepolia USDC 订单进入 finalized。然后把上面的测试矩阵转成一组本地测试数据和一个小型定时沙盒冒烟测试。全部通过后，再按照快速开始把相同的订单与 Webhook 契约接入应用，同时继续让生产凭据远离测试路径。