模拟充值

API 密钥： Payment · 环境： 仅沙箱

在通道上新建一条充值，并把它推进到你指定的阶段，发出与真实付款相同的 webhook，产出与真实付款相同的充值契约。不涉及任何区块链，也不涉及任何服务商。

请求体

参数	类型	必填	说明
amount	string	是	充值金额，十进制字符串，如 "100"
currency	string	是	通道所属项目上已启用的代币，如 USDT
network	string	是	代币到达所用的网络代码，如 TRC20
stage	string	否	confirming、reorged 或 confirmed。默认 confirmed

{
  "amount": "100",
  "currency": "USDT",
  "network": "TRC20",
  "stage": "confirmed"
}

阶段

每次调用都先发出 payment_channel.deposit.confirming，与真实检测的第一步完全一样。stage 决定它停在哪里：

阶段	停在	发出的 webhook
confirming	confirming	confirming
reorged	reorged	先 confirming，再 reorged
confirmed	confirmed	先 confirming，再 confirmed

每次调用都会创建一条新的充值，带一个新的 pcd_。要演练同一笔付款先被重组、再被重新打包，请走接近正式环境的流程，而不是造两条模拟充值——模拟器不做重新打包。

响应 (200 OK)

完整的充值契约，形状与获取通道充值完全一致。

{
  "id": "pcd_7VjMrK3fXd9BzQ4tLnWyGh",
  "payment_channel_id": "pc_2QhKZv6mRt9WdA3nYpLbXf",
  "project_id": "prj_xFukZuAJZR06pLVBh3uwzv",
  "payment_channel_external_id": "customer-42",
  "status": "confirmed",
  "is_final": true,
  "is_test": true,
  "currency": "USDT",
  "network": "TRC20",
  "chain_id": 728126428,
  "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "gross": "100",
  "fee": "1",
  "net": "99",
  "applied_fee_percent": 1.0,
  "customer_fee_percent": 0,
  "tx_hash": "4c8a2f61d05be79341ac6b28e5f0d97341b6ce80a2f5d3719b04ec6a582f1d37",
  "transfer_id": "sandbox:payment-channel-deposit:9a1f7c3e5b8d42069e7a15c0d3b64f28",
  "destination_address": "TQ5mVdC8yPjRs2NbHfW7ZkXe1LoAu4Tg6r",
  "block_height": 0,
  "first_included_block_timestamp": 1767225600,
  "explorer_url": "https://tronscan.org/#/transaction/4c8a2f61d05be79341ac6b28e5f0d97341b6ce80a2f5d3719b04ec6a582f1d37",
  "created_at": 1767225600,
  "updated_at": 1767225600,
  "confirmed_at": 1767225600
}

有两个字段和真实充值不一样，它们都是刻意留下的标记，不是疏漏：block_height 为 0，transfer_id 带 sandbox: 命名空间。正是这两个值让模拟记录进不了任何链上扫描路径。explorer_url 由一个合成哈希生成——它指向的交易在任何链上都不存在。

沙箱里的钱是虚拟的。fee 和 net 按这条充值自己的费率快照计算，金额进入你沙箱余额的方式，与真实充值进入正式余额的方式相同。

规则

• —通道必须是沙箱通道，并且必须用沙箱 Payment key 签名。正式 key 在创建任何东西之前就被拒绝
• —currency + network 必须是项目上已启用、并被沙箱目录接受的代币
• —amount 必须符合该代币的小数精度。小数位过多的金额会被拒绝，而不是被悄悄舍入成另一个数

错误

错误码	HTTP	何时出现
payment_channels_disabled	503	本环境下你的账户未开通收款通道
payment_key_required	403	请求用 Payout（rk_）key 签名
payment_channel_simulation_sandbox_only	403	该通道是正式通道
payment_channel_not_found	404	该 id 解析不到这个凭证可以看到的任何东西
currency_not_enabled_for_project	400	该代币没有在通道所属项目上启用
acceptance_disabled	503	该代币的收款当前未开放
amount_too_many_decimals	400	amount 的小数位超过该代币支持的位数
field_must_be_positive	400	amount 为零或负数
field_invalid_enum	400	currency、network 或 stage 取了未知值

沙箱工作流的全貌见测试，完整错误目录见错误码。