快速入门

从零开始，五分钟内完成一笔已支付的付款，无需持有任何 USDT。

这里的一切都在测试模式下、基于一条模拟链运行。不涉及真实资金，不需要钱包，也不需要测试网水龙头。

1. 获取测试密钥

登录位于 /app 的控制台，打开 API 密钥，创建一个密钥。它以 sk_test_ 开头。决定模式的正是这个前缀——没有任何请求头或标志能把测试密钥变成正式密钥。

export PAYGATE=https://api.paygatehq.com
export KEY=sk_test_...

2. 创建付款

curl -X POST $PAYGATE/v1/payments \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"amount_decimal":"25.00","reference":"order_1"}'

你会得到一笔付款。其中重要的部分如下：

{
  "id": "0d1f…",
  "object": "payment",
  "status": "requires_payment",
  "amount": 25000000,
  "amount_decimal": "25.000000",
  "currency": "USDT",
  "checkout_url": "https://pay.paygatehq.com/c/cs_…",
  "routes": [
    { "chain": "sim", "address": "0x…", "amount": 25000000, "amount_decimal": "25.000000" }
  ],
  "expires_at": 1756300000
}

checkout_url 就是托管页面。把客户引导到那里就大功告成了——页面会显示二维码、精确金额和实时确认进度。

3. 无需任何 USDT 完成付款

curl -X POST $PAYGATE/v1/test/payments/{id}/pay \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $(uuidgen)" -d '{}'

模拟链会接受这笔转账，索引器随即检测到它。轮询这笔付款，观察它的状态变化：

curl $PAYGATE/v1/payments/{id} -H "Authorization: Bearer $KEY"

requires_payment → detected → confirming → paid。

如果不想等待确认数慢慢增加，可以直接推进模拟链：

curl -X POST $PAYGATE/v1/test/advance \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"blocks":12}'

4. 接收 Webhook

注册一个端点，之后每个事件都会投递给它：

curl -X POST $PAYGATE/v1/webhook_endpoints \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://your.app/hooks/paygate","events":["payment.paid","payment.reversed"]}'

响应中会返回签名密钥，仅此一次。请保存好它——验证签名不是可选项，Webhook 指南提供了三种语言的验证代码。

无需创建任何东西，就可以给自己发送一次测试投递：

curl -X POST $PAYGATE/v1/webhook_endpoints/{id}/test \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $(uuidgen)" -d '{}'

5. 演练故障场景

三种用其他方式无法测试的情况：

# 深度超过确认窗口的链重组——paid 变为 reversed
curl -X POST $PAYGATE/v1/test/payments/{id}/reorg -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $(uuidgen)" -d '{}'

少付和逾期付款也可以用同样的方式触发——参见测试模式。

然后

让同一套代码改用 sk_live_ 密钥即可。其他一切都不变：同样的接口、同样的数据结构、同样的事件。测试模式之所以是一个密钥前缀而不是一个单独的主机，全部原因就在于此。