Payloads dos Webhooks
Exemplos dos payloads enviados para cada tipo de evento. Todos os webhooks sao enviados como HTTP POST com Content-Type: application/json.
Headers de seguranca
Cada notificacao inclui os headers X-Owem-Signature (HMAC-SHA256), X-Owem-Timestamp, X-Owem-Event-Id e X-Owem-Event-Type. Consulte Webhooks — Visao Geral para detalhes sobre validacao.
Referencia de Status
Nem todos os eventos significam que a transacao esta concluida. Use a tabela abaixo para saber quando o dinheiro foi efetivamente liquidado.
| Evento | Status | Significado | Dinheiro liquidado? |
|---|---|---|---|
pix.charge.created | created | QR code gerado ou cash-in iniciado. Aguardando pagamento. | Nao — apenas criado |
pix.charge.paid | paid | PIX recebido e liquidado em conta. Saldo atualizado, taxa cobrada. | Sim |
pix.charge.expired | expired | QR code expirou sem pagamento. | N/A |
pix.charge.cancelled | cancelled | QR code cancelado antes de pagamento. | N/A |
pix.payout.processing | processing | PIX enviado, aguardando confirmacao do destino. Saldo reservado (hold). | Nao — pode reverter |
pix.payout.confirmed | settled | PIX enviado confirmado pelo destino. Debito definitivo. | Sim |
pix.payout.failed | rejected | PIX enviado rejeitado pelo destino. Hold liberado, saldo restaurado. | Nao |
pix.payout.returned | returned | PIX enviado devolvido apos liquidacao. | Sim (reverso) |
pix.refund.requested | requested | Devolucao PIX solicitada (MED ou voluntaria). Reserva criada. | Parcial |
pix.refund.completed | completed | Devolucao PIX concluida e liquidada. Debito definitivo. | Sim |
pix.return.received | received | Devolucao PIX recebida (credito na conta). | Sim |
webhook.test | test | Evento de teste disparado manualmente. | N/A |
Regra: Para reconciliacao financeira, so considere definitivos os status paid, settled, received ou completed. Todos os outros sao intermediarios.
Campos comuns
Todos os payloads de webhook incluem estes campos:
| Campo | Tipo | Descricao |
|---|---|---|
event_type | string | Tipo do evento que disparou o webhook (ex: pix.charge.paid) |
status | string | Status da operacao — consulte a Referencia de Status |
account_id | integer | Numero da sua conta na Owem |
entity_id | string (UUID) | Identificador da entidade Owem |
Valores monetarios: Todos os valores sao em subcentavos (1 BRL = 10.000 subcentavos). Para converter para reais: valor / 10000. Exemplo: 300000 / 10000 = R$ 30,00.
pix.charge.paid
Enviado quando um PIX e recebido e liquidado na conta. Este e o evento que confirma que o dinheiro entrou.
Exemplo — vinculado a 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"
}Exemplo — transferencia direta (sem 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"
}| Campo | Tipo | Descricao |
|---|---|---|
event_type | string | Sempre pix.charge.paid |
status | string | Sempre paid |
account_id | integer | Numero da conta que recebeu o PIX |
amount | integer | Valor recebido em subcentavos. 300000 = R$ 30,00 |
fee_amount | integer | Tarifa cobrada em subcentavos. 400 = R$ 0,04 |
end_to_end_id | string | Identificador E2E do BACEN (unico por transacao PIX) |
entity_id | string (UUID) | Identificador da entidade Owem |
tx_id | string ou null | ID da transacao. Presente quando vinculado a um QR code. null para transferencias diretas |
counterparty_name | string ou null | Nome do pagador (remetente) |
external_id | string ou null | Seu identificador externo. Presente quando o QR code foi criado via API com external_id. null para transferencias diretas ou QR sem external_id |
qr_code_id | string ou null | ID do QR code vinculado. null para transferencias diretas |
paid_at | string (ISO 8601) | Data/hora da liquidacao (UTC) |
pix.charge.expired
Disparado automaticamente quando QR code expira (worker a cada 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"
}| Campo | Tipo | Descricao |
|---|---|---|
event_type | string | Sempre pix.charge.expired |
status | string | Sempre expired |
tx_id | string | ID da cobranca/QR code |
external_id | string ou null | Seu identificador externo |
pix.charge.cancelled
Planejado
Este evento esta planejado mas ainda nao esta implementado.
pix.charge.created
Enviado quando um QR code e gerado ou um cash-in e iniciado. Nenhum movimento financeiro ocorreu.
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"
}| Campo | Tipo | Descricao |
|---|---|---|
event_type | string | Sempre pix.charge.created |
status | string | Sempre created |
amount | integer | Valor esperado em subcentavos |
tx_id | string | ID da cobranca/QR code |
external_id | string ou null | Seu identificador externo, retornado tal como enviado. null se nao informado ou QR gerado pelo portal |
pix.payout.confirmed
Enviado quando um PIX enviado e confirmado pela instituicao destino. Debito definitivo.
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."
}
}| Campo | Tipo | Descricao |
|---|---|---|
event_type | string | Sempre pix.payout.confirmed |
status | string | Sempre settled — debito definitivo |
amount | integer | Valor enviado em subcentavos |
fee_amount | integer | Tarifa cobrada em subcentavos |
end_to_end_id | string | Identificador E2E do BACEN |
transaction_id | string (UUID) | Identificador unico da transacao |
external_id | string ou null | Seu identificador externo |
pix_key | string | Chave PIX do destinatario |
description | string ou null | Descricao informada pelo remetente |
recipient | object | Dados bancarios do destinatario (resolvidos via DICT) |
recipient.name | string ou null | Nome do titular da conta destino |
recipient.document | string ou null | CPF/CNPJ do destinatario (somente digitos) |
recipient.ispb | string ou null | ISPB da instituicao destino |
recipient.account | string ou null | Numero da conta destino |
recipient.agency | string ou null | Agencia da conta destino |
recipient.institution_name | string ou null | Nome da instituicao destino |
pix.payout.processing
Enviado quando um PIX enviado esta sendo processado. O saldo esta reservado (hold) mas nao e definitivo.
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."
}
}| Campo | Tipo | Descricao |
|---|---|---|
event_type | string | Sempre pix.payout.processing |
status | string | Sempre processing — saldo reservado, pode reverter |
amount | integer | Valor em subcentavos |
fee_amount | integer | Tarifa em subcentavos (geralmente 0 ate confirmacao) |
end_to_end_id | string | Identificador E2E do BACEN |
transaction_id | string (UUID) | Identificador unico da transacao |
external_id | string ou null | Seu identificador externo |
pix_key | string | Chave PIX do destinatario |
description | string ou null | Descricao informada pelo remetente |
recipient | object | Dados bancarios do destinatario (resolvidos via DICT) |
recipient.name | string ou null | Nome do titular da conta destino |
recipient.document | string ou null | CPF/CNPJ do destinatario (somente digitos) |
recipient.ispb | string ou null | ISPB da instituicao destino |
recipient.account | string ou null | Numero da conta destino |
recipient.agency | string ou null | Agencia da conta destino |
recipient.institution_name | string ou null | Nome da instituicao destino |
pix.payout.failed
Enviado quando um PIX enviado e rejeitado. Hold liberado, saldo restaurado.
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."
}
}| Campo | Tipo | Descricao |
|---|---|---|
event_type | string | Sempre pix.payout.failed |
status | string | Sempre rejected — hold liberado, saldo restaurado |
amount | integer | Valor em subcentavos |
fee_amount | integer | Tarifa em subcentavos (geralmente 0 quando rejeitado) |
end_to_end_id | string | Identificador E2E do BACEN |
transaction_id | string (UUID) | Identificador unico da transacao |
external_id | string ou null | Seu identificador externo |
pix_key | string | Chave PIX do destinatario |
reason | string | Descricao do motivo da rejeicao |
recipient | object | Dados bancarios do destinatario (resolvidos via DICT) |
recipient.name | string ou null | Nome do titular da conta destino |
recipient.document | string ou null | CPF/CNPJ do destinatario (somente digitos) |
recipient.ispb | string ou null | ISPB da instituicao destino |
recipient.account | string ou null | Numero da conta destino |
recipient.agency | string ou null | Agencia da conta destino |
recipient.institution_name | string ou null | Nome da instituicao destino |
pix.payout.returned
Enviado quando um PIX enviado e devolvido apos liquidacao. O payload segue o mesmo formato de 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"
}| Campo | Tipo | Descricao |
|---|---|---|
event_type | string | Sempre pix.payout.returned |
status | string | Sempre returned — PIX enviado devolvido |
amount | integer | Valor devolvido em subcentavos |
return_e2e_id | string | E2E da devolucao |
original_e2e_id | string | E2E da transacao PIX original |
return_code | string | Codigo BACEN da devolucao |
external_id | string ou null | Seu identificador externo da transacao original (se aplicavel) |
pix.refund.requested
Enviado quando uma devolucao PIX e solicitada via MED (Mecanismo Especial de Devolucao). Fundos foram bloqueados cautelarmente na conta do merchant que recebeu o PIX original.
Somente PIX In
Este evento so se aplica a PIX recebidos (cash-in). Se voce enviou um PIX e ele foi devolvido, recebera pix.return.received em vez de 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"
}| Campo | Tipo | Descricao |
|---|---|---|
event_type | string | Sempre pix.refund.requested |
status | string | Sempre requested — bloqueio cautelar ativo |
amount | integer | Valor solicitado para devolucao em subcentavos |
block_id | string (UUID) | Identificador do bloqueio cautelar |
infraction_report_id | string | Identificador da infracao no OnZ |
e2e_id | string | E2E da transacao PIX original que esta sendo contestada |
external_id | string ou null | Seu identificador externo (se aplicavel) |
blocked_amount | integer | Valor efetivamente bloqueado em subcentavos |
fee_amount | integer | Tarifa MED em subcentavos |
fraud_category | string | Categoria da fraude alegada (ex: SCAM, ACCOUNT_TAKEOVER) |
deadline | string (ISO 8601) | Prazo para analise/defesa (UTC) |
scenario | string | Cenario MED: cautelar ou fraude |
created_at | string (ISO 8601) | Data/hora do bloqueio (UTC) |
pix.refund.completed
Enviado quando uma devolucao PIX e processada e concluida.
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"
}| Campo | Tipo | Descricao |
|---|---|---|
event_type | string | Sempre pix.refund.completed |
status | string | Sempre completed — devolucao MED finalizada |
amount | integer | Valor devolvido em subcentavos |
block_id | string (UUID) | Identificador do bloqueio cautelar |
infraction_report_id | string | Identificador da infracao OnZ |
e2e_id | string | E2E da transacao PIX original |
external_id | string ou null | Seu identificador externo (se aplicavel) |
reason | string | Motivo da liberacao (ex: analysis_unfounded, manual_release) |
completed_at | string (ISO 8601) | Data/hora da conclusao (UTC) |
pix.return.received
Enviado quando uma devolucao PIX e recebida (credito na conta).
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
}| Campo | Tipo | Descricao |
|---|---|---|
event_type | string | Sempre pix.return.received |
status | string | Sempre received — credito de devolucao em conta |
return_e2e_id | string | E2E da devolucao |
original_e2e_id | string | E2E da transacao PIX original |
return_code | string | Codigo BACEN da devolucao |
external_id | string ou null | Seu identificador externo da transacao original (se aplicavel) |
webhook.test
Evento de teste disparado manualmente para validar a configuracao do webhook.
json
{
"event_type": "webhook.test",
"status": "test",
"account_id": 10014,
"entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
"message": "Webhook test event"
}Como interpretar os webhooks
Para confirmar que dinheiro entrou na conta: Aguarde pix.charge.paid com status: "paid". Este e o unico evento que garante que o valor foi creditado e a taxa cobrada.
Para confirmar que dinheiro saiu da conta: Aguarde pix.payout.confirmed com status: "settled". O status processing e intermediario — o saldo esta reservado mas pode ser revertido se rejeitado.
Para devolucoes: pix.return.received com status: "received" confirma credito na conta.
Deduplicacao: Use o header X-Owem-Event-Id ou o campo end_to_end_id como chave de idempotencia.