跳到正文

API

本页内容

概览

用签名的、按环境隔离的 webhook 端点和完整的投递工作流，把 Paymos 接入你的后端。

当账单、转出或收款通道充值的状态变化时，Paymos 发送 HTTPS POST。Webhook 是面向你后端的权威异步信号：API 响应只是启动一个操作，webhook 事件告诉你区块链处理之后实际发生了什么。

集成流程

  1. 在 控制台 → 开发者 → Webhook 创建 webhook 端点。
  2. 选择一个或多个事件类目：账单、转出、收款通道。
  3. 可选：把账单和收款通道事件限定到选定项目，两者共用同一个筛选。转出事件为商户级，不受此筛选影响。
  4. 把显示的 whsec_… 密钥存到你的服务器。
  5. 用未改动的原始请求体验证每次投递。
  6. 持久化 event_id，以 2xx 应答，并异步处理事件。

生产与沙箱有各自独立的端点、密钥和事件。沙箱事件绝不投递到生产端点。

端点规则

  • URL 必须使用 HTTPS。
  • 每个商户每个环境最多配置 10 个端点。
  • 同一激活 URL 在一个环境内不能注册两次。
  • 端点必须至少订阅一个类目。
  • 不设项目筛选表示包含所有项目。
  • 暂停或删除端点即停止向其投递新事件。

投递请求头

请求头 契约
Content-Type application/json; charset=utf-8
X-Webhook-Id 稳定的 evt_… 标识；重试和手动重放期间不变
X-Webhook-Timestamp 本次投递尝试的 Unix 秒
X-Webhook-Signature t={timestamp},v1={hmac_hex}；轮换期间可能含两个 v1 值

投递为 at-least-once，不保证顺序。按 X-Webhook-Id 去重，然后应用 data 中的资源状态，而不是数事件或假设到达顺序。

Webhook 文档

模拟通道充值 Webhook 事件