跳到正文

快速开始

本页内容

测试

用专用测试密钥、签名 webhook 和不动真实资金的模拟端点，测试账单与转出的状态变化。

在沙箱中端到端测试你的集成。与生产相同的 API 面、模拟区块链、签名 webhook，不涉及真实资金。

沙箱 vs 生产

特性 沙箱 生产
Base URL api.paymos.io/v1 api.paymos.io/v1
API 密钥 pk_test_ / rk_test_ ID 配 sk_test_ secret pk_live_ / rk_live_ ID 配 sk_live_ secret
交易 模拟 真实区块链
Webhook 正常发送 正常发送
资金 无真实价值 真实加密货币

模拟付款

沙箱付款不会被计时器自动确认。显式触发：

POST/v1/sandbox/invoices/:invoice_id/simulate-payment

请求体：{ "stage": "paid" }——stage 取 paid、overpaid、underpay 或 cancel 之一。像其他签名 /v1 调用一样认证；它只作用于沙箱账单，生产 key 会被拒绝并返回 403 not_sandbox。它发出与真实链上付款相同的生命周期和 webhook 事件，因此你的验证路径在沙箱与生产之间保持一致。

模拟转出

沙箱转出不在真实链上结算。把待处理的沙箱转出标记为已完成，走通你的完整付款流程：

POST/v1/sandbox/withdrawals/:withdrawal_id/simulate-completion

无请求体。用你的 Payout key 像其他 /v1 调用一样认证；它只作用于沙箱转出。它把转出置为 completed 并发出与真实链上付款相同的 withdrawal.completed webhook，因此你的对账路径在沙箱与生产之间保持一致。

模拟通道充值

沙箱收款通道在本地派生地址，不监听任何链，所以充值要显式创建：

POST/v1/sandbox/payment-channels/:payment_channel_id/simulate-deposit

请求体：{ "amount": "100", "currency": "USDT", "network": "TRC20", "stage": "confirmed" }——stage 取 confirming、reorged 或 confirmed，不填默认 confirmed。用沙箱 Payment key 签名；生产 key 在创建任何东西之前就会被拒绝。每次调用都先发出 payment_channel.deposit.confirming，之后是否还有事件、是哪个事件，由你指定的阶段决定，因此你的 webhook 路径在沙箱与生产之间保持一致。完整契约见模拟通道充值。

本地测试 webhook

用隧道把本地服务器暴露到公网：

ngrok http 3000

在 控制台 → 开发者 → Webhook 设置 webhook URL：

https://abc123.ngrok.io/api/paymos-webhook

Webhook 演练场

文档内置一个仅限沙箱的 Playground，向你注册的 URL 投递一个完整签名的事件——无需创建账单即可验证签名处理。

  • 01在沙箱环境中进入 控制台 → 开发者 → 文档
  • 02打开 Webhooks → 测试，然后选择 Playground
  • 03选一个事件类型（invoice.paid、invoice.expired、withdrawal.completed 等）并点击 模拟
  • 04检查服务器日志中收到的事件和 X-Webhook-Signature 请求头

上线前检查清单

  • ☐Webhook 签名验证可用
  • ☐账单创建返回正确数据
  • ☐付款流程重定向正常
  • ☐错误处理覆盖非 2xx 响应（4xx 校验、409 冲突）
  • ☐external_order_id 幂等可用
  • ☐把 API key ID 从 pk_test_ / rk_test_ 换成 pk_live_ / rk_live_，secret 从 sk_test_ 换成 sk_live_
付款流程 身份认证