Skip to main content
PayMatrix 支持以下 Webhook 事件类型，商户可按需订阅。

​
订单事件

​
支付事件

事件类型说明生产可用
order.payment.created支付订单创建✔
order.payment.processing支付处理中✔
order.payment.succeeded支付成功✔
order.payment.failed支付失败✔
order.payment.cancelled支付取消✔

​
退款事件

事件类型说明生产可用
order.refund.created退款申请创建✔
order.refund.processing退款处理中✔
order.refund.succeeded退款成功✔
order.refund.failed退款失败✔

​
争议事件

事件类型说明生产可用
order.dispute.created争议创建✔
order.dispute.evidence_due待提交抗辩材料✔
order.dispute.won商户胜诉✔
order.dispute.lost商户败诉✔
order.dispute.closed争议关闭✔

​
结算事件

事件类型说明
settlement.batch.created结算批次已创建
settlement.batch.completed结算完成（资金已打款）

​
账户事件

事件类型说明
account.balance.changed余额变动
account.disabled账户被禁用

​
Payload 示例

​
支付成功（order.payment.succeeded）

{
  "event_id": "evt_abc123def456",
  "event_type": "order.payment.succeeded",
  "timestamp": 1749081600,
  "data": {
    "order_id": "1000126011700000100001",
    "merchant_transaction_id": "ORDER-20260101-001",
    "amount": 100.00,
    "currency_code": "USD",
    "settlement_amount": 97.00,
    "settlement_currency_code": "USD",
    "status": 2,
    "payment_method": "card",
    "card_brand": "visa",
    "card_last4": "4242",
    "paid_at": "2026-01-01T12:30:00Z"
  }
}

​
支付失败（order.payment.failed）

{
  "event_id": "evt_abc123def789",
  "event_type": "order.payment.failed",
  "timestamp": 1749081600,
  "data": {
    "order_id": "1000126011700000100002",
    "merchant_transaction_id": "ORDER-20260101-002",
    "amount": 100.00,
    "currency_code": "USD",
    "status": 3,
    "failure_reason": "insufficient_funds",
    "failure_message": "Card has insufficient funds"
  }
}

​
退款成功（order.refund.succeeded）

{
  "event_id": "evt_ref123abc456",
  "event_type": "order.refund.succeeded",
  "timestamp": 1749085200,
  "data": {
    "refund_id": "REF-20260101-001",
    "order_id": "1000126011700000100001",
    "original_transaction_id": "ORDER-20260101-001",
    "refund_amount": 50.00,
    "refund_currency": "USD",
    "status": 2,
    "refunded_at": "2026-01-01T13:00:00Z"
  }
}

​
争议创建（order.dispute.created）

{
  "event_id": "evt_dsp123abc456",
  "event_type": "order.dispute.created",
  "timestamp": 1749090000,
  "data": {
    "dispute_id": "dp_abc123",
    "order_id": "1000126011700000100001",
    "dispute_amount": 100.00,
    "dispute_currency": "USD",
    "dispute_reason": "fraudulent",
    "evidence_due_by": "2026-01-15T23:59:59Z"
  }
}

​
结算完成（settlement.batch.completed）

{
  "event_id": "evt_stl123abc456",
  "event_type": "settlement.batch.completed",
  "timestamp": 1749150000,
  "data": {
    "settlement_batch_id": "STL-20260102-001",
    "period_start": "2026-01-01T00:00:00Z",
    "period_end": "2026-01-01T23:59:59Z",
    "total_amount": 9700.00,
    "total_fee": 300.00,
    "net_amount": 9400.00,
    "currency": "USD",
    "transaction_count": 100,
    "settled_at": "2026-01-02T10:00:00Z"
  }
}

​
订阅建议

场景建议订阅的事件
订单状态同步order.payment.succeeded、order.payment.failed、order.payment.cancelled
退款处理order.refund.succeeded、order.refund.failed
争议处理order.dispute.* 全部
财务对账settlement.batch.completed
全面监控全部事件

​
相关页面