Webhook Payloads
Examples of payloads sent for each event type. All webhooks are sent as HTTP POST with Content-Type: application/json.
Security headers
Each notification includes the headers X-Owem-Signature (HMAC-SHA256), X-Owem-Timestamp, X-Owem-Event-Id, and X-Owem-Event-Type. See Webhooks — Overview for validation details.
Status Reference
Not all events mean the transaction is complete. Use the table below to know when funds have actually been settled.
| Event | Status | Meaning | Funds settled? |
|---|---|---|---|
pix.charge.created | created | QR code generated or cash-in initiated. Awaiting payment. | No — just created |
pix.charge.paid | paid | PIX received and settled in account. Balance updated, fee charged. | Yes |
pix.charge.expired | expired | QR code expired without payment. | N/A |
pix.charge.cancelled | cancelled | QR code cancelled before payment. | N/A |
pix.payout.processing | processing | PIX sent, awaiting confirmation from destination. Balance reserved (hold). | No — may revert |
pix.payout.confirmed | settled | PIX sent confirmed by destination. Final debit. | Yes |
pix.payout.failed | rejected | PIX sent rejected by destination. Hold released, balance restored. | No |
pix.payout.returned | returned | PIX sent returned after settlement. | Yes (reverse) |
pix.refund.requested | requested | PIX refund requested (MED or voluntary). Reserve created. | Partial |
pix.refund.completed | completed | PIX refund completed and settled. Final debit. | Yes |
pix.return.received | received | PIX return received (credit to account). | Yes |
webhook.test | test | Manual test event triggered. | N/A |
Rule: For financial reconciliation, only consider paid, settled, received, or completed statuses as final. All others are intermediate.
Common Fields
All webhook payloads include these fields:
| Field | Type | Description |
|---|---|---|
event_type | string | The event that triggered this webhook (e.g., pix.charge.paid) |
status | string | Operation status — see Status Reference |
account_id | integer | Your account number at Owem |
entity_id | string (UUID) | Owem entity identifier |
Monetary values: All amounts are in subcentavos (1 BRL = 10,000 subcentavos). To convert to BRL: amount / 10000. Example: 300000 / 10000 = R$ 30.00.
pix.charge.paid
Sent when a PIX is received and settled in the account. This is the event that confirms the money has arrived.
Example — linked to QR code
json
{
"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",
"external_id": "order-9876",
"paid_at": "2026-04-02T09:58:05Z"
}Example — direct transfer (no QR)
json
{
"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",
"external_id": null,
"paid_at": "2026-04-02T10:15:22Z"
}| Field | Type | Description |
|---|---|---|
event_type | string | Always pix.charge.paid |
status | string | Always paid |
account_id | integer | Account number that received the PIX |
amount | integer | Amount received in subcentavos. 300000 = R$ 30.00 |
fee_amount | integer | Fee charged in subcentavos. 400 = R$ 0.04 |
end_to_end_id | string | BACEN end-to-end identifier (unique per PIX transaction) |
entity_id | string (UUID) | Owem entity identifier |
tx_id | string or null | Transaction ID. Present when linked to a QR code. null for direct transfers |
counterparty_name | string or null | Name of the payer (sender) |
external_id | string or null | Your external identifier. Present when the QR code was created via API with external_id. null for direct transfers or QR codes without external_id |
qr_code_id | string or null | Linked QR code ID. null for direct transfers |
paid_at | string (ISO 8601) | Settlement timestamp (UTC) |
pix.charge.expired
Triggered automatically when a QR code expires (worker runs every 5 min).
json
{
"event_type": "pix.charge.expired",
"status": "expired",
"account_id": 10014,
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"tx_id": "abc123def456ghi789",
"external_id": "order-9876"
}| Field | Type | Description |
|---|---|---|
event_type | string | Always pix.charge.expired |
status | string | Always expired |
tx_id | string | Charge/QR code ID |
external_id | string or null | Your external identifier |
pix.charge.cancelled
Planned
This event is planned but not yet implemented.
pix.charge.created
Sent when a QR code is generated or a cash-in is initiated. No financial movement has occurred.
json
{
"event_type": "pix.charge.created",
"status": "created",
"account_id": 10014,
"amount": 500000,
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"tx_id": "abc123def456ghi789",
"external_id": "order-9876"
}| Field | Type | Description |
|---|---|---|
event_type | string | Always pix.charge.created |
status | string | Always created |
amount | integer | Expected amount in subcentavos |
tx_id | string | Charge/QR code ID |
external_id | string or null | Your external identifier, returned as provided. null if not set or QR generated via portal |
pix.payout.confirmed
Sent when a PIX payout is confirmed by the destination institution. Final debit.
json
{
"event_type": "pix.payout.confirmed",
"status": "settled",
"account_id": 10014,
"amount": 500000,
"fee_amount": 200,
"end_to_end_id": "E3783905920260402101500000001",
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"external_id": "payment-456",
"pix_key": "destinatario@email.com",
"description": "Pagamento fornecedor",
"recipient": {
"name": "EMPRESA DESTINO LTDA",
"document": "12345678000199",
"ispb": "60701190",
"account": "12345678",
"agency": "0001",
"institution_name": "Itau Unibanco S.A."
}
}| Field | Type | Description |
|---|---|---|
event_type | string | Always pix.payout.confirmed |
status | string | Always settled — final debit |
amount | integer | Amount sent in subcentavos |
fee_amount | integer | Fee charged in subcentavos |
end_to_end_id | string | BACEN end-to-end identifier |
transaction_id | string (UUID) | Unique transaction identifier |
external_id | string or null | Your external identifier |
pix_key | string | Recipient PIX key |
description | string or null | Description provided by sender |
recipient | object | Recipient bank details (resolved via DICT) |
recipient.name | string or null | Name of the destination account holder |
recipient.document | string or null | Recipient CPF/CNPJ (digits only) |
recipient.ispb | string or null | Destination institution ISPB |
recipient.account | string or null | Destination account number |
recipient.agency | string or null | Destination account agency |
recipient.institution_name | string or null | Destination institution name |
pix.payout.processing
Sent when a PIX payout is being processed. Balance is reserved (hold) but not final.
json
{
"event_type": "pix.payout.processing",
"status": "processing",
"account_id": 10014,
"amount": 500000,
"fee_amount": 0,
"end_to_end_id": "E3783905920260402101500000001",
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"external_id": "payment-456",
"pix_key": "destinatario@email.com",
"description": "Pagamento fornecedor",
"recipient": {
"name": "EMPRESA DESTINO LTDA",
"document": "12345678000199",
"ispb": "60701190",
"account": "12345678",
"agency": "0001",
"institution_name": "Itau Unibanco S.A."
}
}| Field | Type | Description |
|---|---|---|
event_type | string | Always pix.payout.processing |
status | string | Always processing — balance reserved, may revert |
amount | integer | Amount in subcentavos |
fee_amount | integer | Fee in subcentavos (usually 0 until confirmation) |
end_to_end_id | string | BACEN end-to-end identifier |
transaction_id | string (UUID) | Unique transaction identifier |
external_id | string or null | Your external identifier |
pix_key | string | Recipient PIX key |
description | string or null | Description provided by sender |
recipient | object | Recipient bank details (resolved via DICT) |
recipient.name | string or null | Name of the destination account holder |
recipient.document | string or null | Recipient CPF/CNPJ (digits only) |
recipient.ispb | string or null | Destination institution ISPB |
recipient.account | string or null | Destination account number |
recipient.agency | string or null | Destination account agency |
recipient.institution_name | string or null | Destination institution name |
pix.payout.failed
Sent when a PIX payout is rejected. Hold released, balance restored.
json
{
"event_type": "pix.payout.failed",
"status": "rejected",
"account_id": 10014,
"amount": 500000,
"fee_amount": 0,
"end_to_end_id": "E3783905920260402101500000001",
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"external_id": "payment-456",
"pix_key": "destinatario@email.com",
"reason": "Conta destinatario nao encontrada",
"recipient": {
"name": "EMPRESA DESTINO LTDA",
"document": "12345678000199",
"ispb": "60701190",
"account": "12345678",
"agency": "0001",
"institution_name": "Itau Unibanco S.A."
}
}| Field | Type | Description |
|---|---|---|
event_type | string | Always pix.payout.failed |
status | string | Always rejected — hold released, balance restored |
amount | integer | Amount in subcentavos |
fee_amount | integer | Fee in subcentavos (usually 0 when rejected) |
end_to_end_id | string | BACEN end-to-end identifier |
transaction_id | string (UUID) | Unique transaction identifier |
external_id | string or null | Your external identifier |
pix_key | string | Recipient PIX key |
reason | string | Rejection reason description |
recipient | object | Recipient bank details (resolved via DICT) |
recipient.name | string or null | Name of the destination account holder |
recipient.document | string or null | Recipient CPF/CNPJ (digits only) |
recipient.ispb | string or null | Destination institution ISPB |
recipient.account | string or null | Destination account number |
recipient.agency | string or null | Destination account agency |
recipient.institution_name | string or null | Destination institution name |
pix.payout.returned
Sent when a PIX payout is returned after settlement. The payload follows the same format as pix.return.received.
json
{
"event_type": "pix.payout.returned",
"status": "returned",
"account_id": 10014,
"amount": 300000,
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"return_e2e_id": "D9040088820260402111500000001",
"original_e2e_id": "E9040088820260402095758709999671",
"return_code": "MD06",
"external_id": "payment-456"
}| Field | Type | Description |
|---|---|---|
event_type | string | Always pix.payout.returned |
status | string | Always returned — PIX payout returned |
amount | integer | Amount returned in subcentavos |
return_e2e_id | string | Return E2E identifier |
original_e2e_id | string | E2E of the original PIX transaction |
return_code | string | BACEN return code |
external_id | string or null | Your external identifier from the original transaction (if applicable) |
pix.refund.requested
Sent when a PIX refund is requested via MED (Special Return Mechanism). Funds have been precautionarily blocked in the merchant account that received the original PIX.
PIX In only
This event only applies to received PIX payments (cash-in). If you sent a PIX and it was returned, you will receive pix.return.received instead of pix.refund.*.
json
{
"event_type": "pix.refund.requested",
"status": "requested",
"account_id": 10014,
"amount": 300000,
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"block_id": "b1c2d3e4-f5g6-7890-hijk-lm1234567890",
"infraction_report_id": "INF20260402001",
"e2e_id": "E9040088820260402095758709999671",
"external_id": null,
"blocked_amount": 300000,
"fee_amount": 0,
"fraud_category": "SCAM",
"deadline": "2026-04-09T14:30:00Z",
"scenario": "cautelar",
"created_at": "2026-04-02T14:30:00Z"
}| Field | Type | Description |
|---|---|---|
event_type | string | Always pix.refund.requested |
status | string | Always requested — precautionary block active |
amount | integer | Amount requested for refund in subcentavos |
block_id | string (UUID) | Precautionary block identifier |
infraction_report_id | string | Infraction identifier at OnZ |
e2e_id | string | E2E of the original PIX transaction being disputed |
external_id | string or null | Your external identifier (if applicable) |
blocked_amount | integer | Amount effectively blocked in subcentavos |
fee_amount | integer | MED fee in subcentavos |
fraud_category | string | Alleged fraud category (e.g., SCAM, ACCOUNT_TAKEOVER) |
deadline | string (ISO 8601) | Deadline for analysis/defense (UTC) |
scenario | string | MED scenario: cautelar or fraude |
created_at | string (ISO 8601) | Block timestamp (UTC) |
pix.refund.completed
Sent when a PIX refund is processed and completed.
json
{
"event_type": "pix.refund.completed",
"status": "completed",
"account_id": 10014,
"amount": 300000,
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"block_id": "b1c2d3e4-f5g6-7890-hijk-lm1234567890",
"infraction_report_id": "INF20260402001",
"e2e_id": "E9040088820260402095758709999671",
"external_id": null,
"reason": "analysis_unfounded",
"completed_at": "2026-04-02T14:30:00Z"
}| Field | Type | Description |
|---|---|---|
event_type | string | Always pix.refund.completed |
status | string | Always completed — MED refund finalized |
amount | integer | Amount refunded in subcentavos |
block_id | string (UUID) | Precautionary block identifier |
infraction_report_id | string | OnZ infraction identifier |
e2e_id | string | E2E of the original PIX transaction |
external_id | string or null | Your external identifier (if applicable) |
reason | string | Release reason (e.g., analysis_unfounded, manual_release) |
completed_at | string (ISO 8601) | Completion timestamp (UTC) |
pix.return.received
Sent when a PIX return is received (credit to account).
json
{
"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",
"external_id": null
}| Field | Type | Description |
|---|---|---|
event_type | string | Always pix.return.received |
status | string | Always received — return credit applied |
return_e2e_id | string | Return E2E identifier |
original_e2e_id | string | E2E of the original PIX transaction |
return_code | string | BACEN return code |
external_id | string or null | Your external identifier from the original transaction (if applicable) |
webhook.test
Manual test event triggered to validate webhook configuration.
json
{
"event_type": "webhook.test",
"status": "test",
"account_id": 10014,
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"message": "Webhook test event"
}How to interpret webhooks
To confirm money has arrived: Wait for pix.charge.paid with status: "paid". This is the only event that guarantees the amount was credited and the fee was charged.
To confirm money was sent: Wait for pix.payout.confirmed with status: "settled". The processing status is intermediate — balance is reserved but may be reversed if rejected.
For returns: pix.return.received with status: "received" confirms credit to account.
Deduplication: Use the X-Owem-Event-Id header or the end_to_end_id field as an idempotency key.