OnnixPay

Webhooks

Tipos de evento

O catálogo completo, agrupado por recurso. O nome segue sempre a convenção recurso.acao. Novos tipos podem ser adicionados a qualquer momento, então trate o que você conhece e ignore o resto.

Cobrança

Eventos das cobranças criadas em POST /v1/charges (PIX ou boleto).

charge.createdeventoopcional
Cobrança criada. Traz o br_code e o txid do PIX, ou a linha digitável do boleto.
charge.paideventoopcional
Pagamento confirmado. A cobrança passa a paid e o end_to_end_id é preenchido. É o evento que libera o pedido.
charge.expiredeventoopcional
A cobrança venceu sem ter sido paga.
charge.canceledeventoopcional
A cobrança foi cancelada antes do pagamento.
charge.disputedeventoopcional
Uma cobrança já paga entrou em disputa (MED). O valor fica retido enquanto o caso é analisado.
charge.refundedeventoopcional
A cobrança foi estornada ao pagador, por devolução ou disputa confirmada.

PIX

Movimentos PIX na conta, incluindo os que não vêm de cobranças.

pix.in.completedeventoopcional
PIX recebido e creditado no saldo disponível.
pix.qrcode.paideventoopcional
Um QR Code seu foi pago.
pix.out.completedeventoopcional
PIX enviado e liquidado na rede. O data é o mesmo recurso de GET /v1/payouts/:id, incluindo reference e recipient, então dá para conciliar sem uma consulta extra.
pix.out.failedeventoopcional
PIX enviado falhou; o valor reservado volta ao saldo disponível. Mesmo formato do evento de sucesso, com o motivo em failure_reason.
pix.refundedeventoopcional
Devolução de um PIX recebido foi efetivada.
pix.reversal.ineventoopcional
Devolução recebida: um PIX que você enviou voltou para a sua conta.
pix.reversal.outeventoopcional
Devolução enviada: um PIX que você recebeu foi devolvido ao pagador.

Infração / MED

O MED (Mecanismo Especial de Devolução) é o processo do Banco Central para contestação de PIX suspeito de fraude. O ciclo tem três momentos: a infração é aberta, analisada e depois confirmada ou negada.

pix.infraction.openedeventoopcional
Infração aberta. Um PIX recebido foi contestado. O valor é retido do saldo disponível enquanto o caso é analisado, e a transação passa a IN_DISPUTE.
pix.infraction.confirmedeventoopcional
Infração confirmada. A contestação foi aceita: a fraude é dada como comprovada e o valor retido é estornado ao pagador. decision é ACCEPT.
pix.infraction.rejectedeventoopcional
Infração negada. A contestação foi recusada: a transação é considerada legítima e o valor retido volta ao seu saldo disponível. decision é REJECT.
pix.infraction.resolvedeventoopcional
Encerramento do caso, qualquer que seja o desfecho. É disparado junto com pix.infraction.confirmed ou pix.infraction.rejected.

Não assine os dois caminhos

Escolha entre o evento genérico e os específicos. Se você assinar pix.infraction.resolved e pix.infraction.confirmed, vai receber duas notificações para a mesma resolução.

TED

ted.in.completedeventoopcional
TED recebida e creditada no saldo.
ted.out.completedeventoopcional
TED enviada e liquidada.
ted.out.failedeventoopcional
TED enviada falhou. O valor reservado volta ao saldo disponível.

Boleto

boleto.createdeventoopcional
Boleto emitido. Traz linha digitável, código de barras e vencimento.
boleto.paideventoopcional
Boleto liquidado e valor creditado no saldo.
boleto.expiredeventoopcional
Boleto venceu sem pagamento.
boleto.canceledeventoopcional
Boleto baixado antes do pagamento.

Pagamento de contas

bill_payment.completedeventoopcional
A conta foi paga com o seu saldo.
bill_payment.failedeventoopcional
O pagamento falhou. O valor reservado volta ao saldo disponível.
bill_payment.reversedeventoopcional
Pagamento estornado pelo banco recebedor; o valor volta ao saldo.

Conta

transfer.internal.ineventoopcional
Transferência interna recebida (entre contas da plataforma).
transfer.internal.outeventoopcional
Transferência interna enviada.
balance.updatedeventoopcional
O saldo mudou. Use como gatilho para reconsultar GET /v1/balance.
account.status.changedeventoopcional
A conta mudou de situação (ativa, bloqueada, encerrada).
kyc.approvedeventoopcional
O cadastro foi aprovado e a conta pode transacionar.
kyc.rejectedeventoopcional
O cadastro foi reprovado.

Teste

webhook.pingeventoopcional
Disparado quando você testa o endpoint pelo dashboard. Serve para validar URL, assinatura e resposta 2xx sem mexer em dinheiro.

Campos comuns

referencestring | nullopcional
O seu identificador, ecoado exatamente como enviado na criação. Use-o para casar o evento com o pedido no seu sistema.
payerobjectopcional
Pagador real: nome e documento que o banco identificou na liquidação. É o que aparece no extrato. Enquanto a cobrança não é paga, repete o pagador solicitado.
payer_requestobjectopcional
Pagador solicitado: o que você (ou o checkout) enviou no payload da criação. Serve para conferir se quem pagou é quem deveria pagar.
amountinteger | stringopcional
Valor sempre em centavos, nunca em ponto flutuante. Vem como inteiro nos eventos de cobrança e pagamento, e como string nos eventos de infração (evita perda de precisão). Converta antes de comparar.

Boas práticas de consumo

  • Trate cada tipo pelo campo type e ignore os desconhecidos.
  • Deduplique pelo id do evento, porque pode haver reentrega.
  • Não assuma ordem de chegada; confie no status do data.
  • Nunca decida por dinheiro só pelo nome do evento: confirme o valor em data.amount.
Payloads
{
  "id": "019e8f03-2d48-7f9b-9d8e-eb22404754b2",
  "type": "charge.created",
  "created_at": "2026-06-03T19:46:33.6Z",
  "data": {
    "id": "019e8f03-2d48-7f9b-9d8e-eb22404754b2",
    "object": "charge",
    "amount": 2599,
    "currency": "BRL",
    "method": "pix",
    "status": "pending",
    "txid": "kk6g232xel65a0daee4dd13kk4000637343",
    "br_code": "00020101...6304CACD",
    "reference": "pedido-1042",
    "payer": { "name": "Maria Souza", "document": "62363692322" },
    "payer_request": { "name": "Maria Souza", "document": "62363692322" },
    "expires_at": "2026-06-03T20:16:32.703Z",
    "created_at": "2026-06-03T19:46:33.585Z"
  }
}
AnteriorVisão geralPróximo Verificar assinatura