沙箱与测试

沙箱如何工作

• 使用 ok_test_… Key。订单为 environment: "SANDBOX"，生产 Key 看不到。
• 使用真实的 HTP 钱包和真实 USDT，但只在你和你的测试用户之间流转 —— 其他人无法付款或收款（SANDBOX_USER_ONLY）。
• 手续费照常计算，随后返还到你的钱包。
• 限额取审核限额与单笔 100、日 500、月 2000 USDT 中的较小值，与生产分开累计。
• App 未发布也可使用。

设置测试用户

在控制台测试用户 → 添加（最多 20 个）HTP 账号。每个测试用户需要：

1. 用 HTP 快捷登录登录你的 App —— 这样才会产生你可以收款的 sub。
2. 在 HTP App 中有一定 USDT 余额并已设置支付 PIN。

你（开发者）可以登录自己的沙箱 App，但不能向自己的 App 付款（SELF_PAYMENT_FORBIDDEN）—— 请用测试用户付款。

测试用例

#	场景	预期
1	创建收款单 → 测试用户在 HTP App 中付款	收到并验签 payment.paid；订单 PAID
2	用相同 Idempotency-Key 重试创建请求	返回同一个 id，只有一笔订单
3	相同 out_order_no，新的 Idempotency-Key	409 ORDER_ALREADY_EXISTS
4	expire_minutes: 1，等待过期	订单为 CLOSED，无 checkout_url，收银台提示已过期
5	关闭 CREATED 收款单后打开链接	收银台提示已关闭；订单 CLOSED
6	部分退款，再退剩余部分	两张 REFUND 单，两次 payment.refunded，refunded_amount = amount
7	退款超过剩余金额	422 REFUND_AMOUNT_EXCEEDED
8	金额超过 100 USDT	422 LIMIT_EXCEEDED
9	payer_sub 为从未登录的用户	422 USER_NOT_AUTHORIZED
10	错误密钥 / 过期时间戳 / 重复 nonce	401 SIGNATURE_INVALID
11	篡改请求体的回调（用回调验签构造）	你的接口返回 401
12	同一回调投递两次（控制台重发）	只处理一次
13	停掉服务，付款，几分钟后再启动	回调重试成功；或在控制台重发
14	下载账单 CSV	与你的数据库一致
15	向测试用户付款（如已开通）	SUCCEEDED，收到 payout.completed

排查问题

• 每个响应都有 trace_id —— 请记录。
• 控制台回调记录展示每次投递的 last_status_code 和 last_error。
• SIGNATURE_INVALID：用签名生成器输入相同参数，比对 string_to_sign。
• 回调地址必须能通过公网 HTTPS（有效证书）访问并解析到公网 IP。本地调试可使用内网穿透（ngrok、Cloudflare Tunnel），把隧道地址设为回调地址。