Skip to main content
Webhooks de pagamento sempre usam o envelope de transaction. O event de topo permanece transaction; o nome concreto do evento fica em data.event_type.

​
Exemplo de payload entregue

data.customer traz quem comprou: name, email e phone (o phone pode vir null). O documento do comprador nunca é enviado. O bloco vem null quando a transação não tem comprador resolvível. data.products traz os itens comprados, na mesma forma que o endpoint de detalhe da transação devolve: o id público do item, title, unit_price, quantity, tangible e kind. A lista vem vazia quando a transação não tem itens. unit_price é inteiro, na menor unidade da moeda, igual ao amount — 10000 numa venda em BRL é R$ 100,00. tangible diz se o item exige envio. kind é product, order_bump ou upsell; brinde chega como product com preço 0, e não como um tipo próprio. data.attribution traz de onde a venda veio: UTMs de campanha, click IDs de anúncio (fbc, fbp, gclid, ttclid), o par de afiliado (src, sck) e as URLs de checkout e origem. Cada chave vem null quando ausente, e o bloco inteiro vem null em transações criadas pela API — a atribuição vive na sessão de checkout, que essas vendas não têm. data.store diz em qual loja a venda aconteceu: o id público da vitrine e o nome dela. É o que permite separar as marcas quando a mesma conta tem mais de uma e todas apontam para o mesmo endpoint. O bloco vem null — e sempre presente, nunca omitido — quando a venda não tem vitrine registrada: cobrança pela API, cobrança manual e split. Vendas anteriores à chegada das vitrines também chegam null, então leia null como “sem vitrine registrada”, e não como prova de que a venda não veio de uma.
Esses blocos são aditivos e foram introduzidos juntos. Trate-os como opcionais: mantenha seu handler funcionando quando algum faltar, e não condicione a liberação do pedido à presença deles.
data.informations devolve o array informations que você enviou ao criar a transação via API — use-o para reconciliar o evento com os seus próprios registros. Só aparece quando você enviou entradas customizadas na criação; transações sem elas (ou criadas por checkout links) omitem o campo.

​
Resposta de ACK

​
Eventos emitidos hoje

  • transaction.created
  • transaction.pending
  • transaction.paid
  • transaction.cancelled
  • transaction.refunded
  • transaction.partially_refunded
  • transaction.chargedback
  • transaction.three_ds_required
  • transaction.med — só por assinatura explícita
  • transaction.pre_chargedback — só por assinatura explícita
Os dois últimos são eventos dedicados de reversão. Eles chegam apenas a webhooks que os listam na seleção de eventos: um webhook em “todos os eventos” nunca os recebe, porque a mesma reversão já chega nele como transaction.refunded. Assine no painel (Configurações → Webhooks) quando quiser distinguir um MED do PIX ou um pré-chargeback de um estorno comum. Quando a reversão é um MED ou um pré-chargeback, a entrega de transaction.refunded dela leva data.status como med ou pre_chargedback, e não refunded. O nome do evento é estável; o campo de status é o mais específico.

​
Erro comum de ingestão

Como corrigir: faça deduplicação pelo id do evento no topo, não pelo ID da transaction, porque a mesma transaction pode emitir mais de um evento ao longo do tempo.

​
Guia de mapeamento

  • Use transaction.paid para liberar bens ou serviços.
  • Mantenha o pedido aberto em transaction.pending.
  • Para method: "voucher", transaction.pending também pode carregar instruções de pagamento em data.voucher. Exiba url, digitable_line, barcode ou instructions e continue aguardando transaction.paid.
  • Use eventos de reembolso e chargeback para fluxos de financeiro e suporte.
  • Encaminhe transaction.three_ds_required de volta para o seu fluxo de challenge de cartão.