API 参考

Webhook

投递请求头、事件载荷、重试和投递日志。

回调 URL

在开发者集成设置中配置团队 callback URL。MakePay 会先检查 MakePay 产品设置，再检查共享开发者回调设置，因此在产品专用设置逐步推出期间，现有 MakeSwap Webhook 设置也可以接收 MakePay 支付事件。

保存 MakePay callback URL 时，MakeCrypto 会生成 webhook secret。请把它保存在后端密钥管理器中。你可以随时从同一设置页重新生成；重新生成后，请先更新后端，再用新 secret 强制验证签名。

投递行为

MakePay 以 POST 请求发送支付和订阅 Webhook，请求体为 JSON。失败投递最多重试十次，每次间隔五分钟。也可以从 MakeCrypto Webhook 请求日志手动重发。

请求头

content-type: application/json
user-agent: MakePay-Webhooks/1.0
x-makepay-delivery-id: 9f1c6cf4-8514-4ee5-80fd-8e8fe2b5e313
x-makepay-delivery-group-id: 9f1c6cf4-8514-4ee5-80fd-8e8fe2b5e313
x-makepay-delivery-origin: event
x-makepay-event: status_changed
x-makepay-attempt: 1
x-makepay-signature: t=1776556800,v1=7d4b3f...

验证签名

MakePay 会用 HMAC-SHA256 对原始 JSON 请求体签名。签名载荷是：

{timestamp}.{raw_request_body}

x-makepay-signature 请求头包含 Unix 时间戳和带版本的摘要：

t=1776556800,v1=<hex_hmac_sha256>

在解析 JSON 前读取原始请求体。如果框架会先解析请求体，请配置 Webhook 路由暴露原始请求字节，并在信任载荷前验证这些字节。

支付载荷

支付 Webhook 包含投递 ID、事件类型、创建时间、事件触发原因、支付链接摘要，以及最新支付会话。会话字段包含状态、之前状态、发票资产和金额、客户选择的卖出资产、目标地址、充值地址、channel ID、源链、过期时间、结算对象和错误信息。

{
  "deliveryId": "9f1c6cf4-8514-4ee5-80fd-8e8fe2b5e313",
  "type": "makepay.payment.status_changed",
  "createdAt": "2026-04-19T00:00:00.000Z",
  "event": {
    "type": "status_changed",
    "trigger": "payment_status_reconcile"
  },
  "paymentLink": {
    "uid": "01hzy4k6p4w9y2x7e2z7n8a2xm",
    "status": "active",
    "publicUrl": "https://makepay.io/payment/01hzy4k6p4w9y2x7e2z7n8a2xm",
    "amount": "129.99",
    "currency": "USDT",
    "merchantOrderId": "order_1042",
    "clientEmail": "buyer@example.com"
  },
  "session": {
    "status": "complete",
    "previousStatus": "pending",
    "invoiceAsset": "USDT",
    "invoiceAmount": "129.99",
    "sourceChain": "ETH"
  }
}

事件类型

status_changed：支付会话状态变化。
settlement_updated：状态对账后结算数据变化。
payment_request_expired、quote_expired 和 payment_cancelled_by_payer：终态未付款结果。
channel_created：付款人接受报价，MakePay 创建充值 channel。
subscription_status_changed：MakePay 订阅在 active、paused、overdue 或 cancelled 间切换。

quote_created 和 quote_refreshed 是内部支付时间线事件，不会发送到 callback URL。

订阅状态载荷

订阅状态变化时 MakePay 也会发送回调。当最早未支付计费周期超过 dueAt 至少 24 小时时，调度器会把订阅标记为 overdue；当不再有超过 24 小时 overdue 的未支付周期时，会把订阅移回 active。商户和客户门户触发的状态变化使用同一回调。

载荷包含 subscription、当前 cycle 和 data.previousStatus、data.nextStatus、data.reason 等状态转换信息。

投递日志 API

使用 Webhook 请求路由查看投递和重试。

GET /api/partner/v1/makepay/webhook-requests?limit=100

可选过滤器包括 paymentLinkUid、deliveryStatus 和 search。