Webhook Payload

各事件类型发送的 payload 示例。所有 Webhook 以 HTTP POST 方式发送，Content-Type: application/json。

安全头

每个通知包含 X-Owem-Signature（HMAC-SHA256）、X-Owem-Timestamp、X-Owem-Event-Id 和 X-Owem-Event-Type 头。详见 Webhooks — 概览。

---

状态参考

并非所有事件都意味着交易已完成。请使用下表了解资金何时已实际结算。

事件	状态	含义	资金已结算？
pix.charge.created	created	QR 码已生成或收款已发起。等待付款。	否 — 仅创建
pix.charge.paid	paid	PIX 已收到并结算到账。余额已更新，手续费已扣除。	是
pix.charge.expired	expired	QR 码已过期，未收到付款。	不适用
pix.charge.cancelled	cancelled	QR 码在付款前已取消。	不适用
pix.payout.processing	processing	PIX 已发送，等待目标确认。余额已预留（hold）。	否 — 可能撤销
pix.payout.confirmed	settled	PIX 发送已被目标确认。最终扣款。	是
pix.payout.failed	rejected	PIX 发送被目标拒绝。预留已释放，余额已恢复。	否
pix.payout.returned	returned	PIX 发送在结算后被退回。	是（反向）
pix.refund.requested	requested	PIX 退款已请求（MED 或自愿）。预留已创建。	部分
pix.refund.completed	completed	PIX 退款已完成并结算。最终扣款。	是
pix.return.received	received	PIX 退回已收到（入账）。	是
webhook.test	test	手动触发的测试事件。	不适用

规则：财务对账时，仅 paid、settled、received 或 completed 状态为最终状态。其他均为中间状态。

---

公共字段

所有 webhook payload 包含以下字段：

字段	类型	描述
event_type	string	触发 webhook 的事件类型（如 pix.charge.paid）
status	string	操作状态 — 参见状态参考
account_id	integer	您在 Owem 的账户号码
entity_id	string (UUID)	Owem 实体标识符

金额单位：所有金额以子分为单位（1 BRL = 10,000 子分）。转换为雷亚尔：金额 / 10000。示例：300000 / 10000 = R$ 30.00。

---

pix.charge.paid

PIX 收款已结算到账时发送。此事件确认资金已到账。

示例 — 关联 QR 码

{
  "event_type": "pix.charge.paid",
  "status": "paid",
  "account_id": 10014,
  "amount": 300000,
  "fee_amount": 400,
  "end_to_end_id": "E9040088820260402095758709999671",
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "tx_id": "u5f26sfyrq4plkw7tjwa",
  "counterparty_name": "MARIA SANTOS",
  "paid_at": "2026-04-02T09:58:05Z"
}

示例 — 直接转账（无 QR 码）

{
  "event_type": "pix.charge.paid",
  "status": "paid",
  "account_id": 10014,
  "amount": 300000,
  "fee_amount": 400,
  "end_to_end_id": "E9040088820260402095758709999671",
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "tx_id": null,
  "counterparty_name": "JOAO SILVA",
  "paid_at": "2026-04-02T10:15:22Z"
}

字段	类型	描述
event_type	string	始终为 pix.charge.paid
status	string	始终为 paid
account_id	integer	收款账户号码
amount	integer	收款金额（子分）。300000 = R$ 30.00
fee_amount	integer	手续费（子分）。400 = R$ 0.04
end_to_end_id	string	BACEN E2E 标识符（每笔 PIX 交易唯一）
entity_id	string (UUID)	Owem 实体标识符
tx_id	string 或 null	交易 ID。关联 QR 码时存在。直接转账时为 null
counterparty_name	string 或 null	付款方（发送方）名称
paid_at	string (ISO 8601)	结算时间戳（UTC）

---

pix.charge.created

QR 码生成或收款发起时发送。无任何资金变动。

{
  "event_type": "pix.charge.created",
  "status": "created",
  "account_id": 10014,
  "amount": 500000,
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "tx_id": "abc123def456ghi789"
}

---

pix.payout.confirmed

PIX 发送已被目标机构确认时发送。最终扣款。

{
  "event_type": "pix.payout.confirmed",
  "status": "settled",
  "account_id": 10014,
  "amount": 500000,
  "end_to_end_id": "E3783905920260402101500000001",
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "pix_key": "destinatario@email.com",
  "description": "供应商付款"
}

---

pix.payout.processing

PIX 发送正在处理时发送。余额已预留（hold）但非最终。

{
  "event_type": "pix.payout.processing",
  "status": "processing",
  "account_id": 10014,
  "amount": 500000,
  "end_to_end_id": "E3783905920260402101500000001",
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7"
}

---

pix.payout.failed

PIX 发送被拒绝时发送。预留已释放，余额已恢复。

{
  "event_type": "pix.payout.failed",
  "status": "rejected",
  "account_id": 10014,
  "amount": 500000,
  "end_to_end_id": "E3783905920260402101500000001",
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "error_reason": "收款账户未找到"
}

---

pix.refund.completed

PIX 退款处理完成时发送。

{
  "event_type": "pix.refund.completed",
  "status": "completed",
  "account_id": 10014,
  "amount": 300000,
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "original_end_to_end_id": "E9040088820260402095758709999671",
  "return_code": "MD06"
}

---

pix.return.received

PIX 退回收到时发送（入账）。

{
  "event_type": "pix.return.received",
  "status": "received",
  "account_id": 10014,
  "amount": 300000,
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "return_e2e_id": "D9040088820260402111500000001",
  "original_e2e_id": "E9040088820260402095758709999671",
  "return_code": "MD06"
}

---

webhook.test

手动触发的测试事件，用于验证 webhook 配置。

{
  "event_type": "webhook.test",
  "status": "test",
  "account_id": 10014,
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "message": "Webhook test event"
}

---

如何解读 Webhook

确认资金已到账：等待 pix.charge.paid，status: "paid"。这是唯一确认金额已入账且手续费已扣除的事件。

确认资金已发出：等待 pix.payout.confirmed，status: "settled"。processing 状态为中间状态 — 余额已预留但可能因拒绝而撤销。

退回：pix.return.received，status: "received" 确认资金已入账。

去重：使用 X-Owem-Event-Id 头或 end_to_end_id 字段作为幂等键。