Pular para o conteúdo principal
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

{
  "id": "evt_pay_1001",
  "event": "transaction",
  "api_version": "v1",
  "data": {
    "id": "tr_3001",
    "event_type": "transaction.pending",
    "correlation_id": "order_3001",
    "method": "voucher",
    "status": "pending",
    "amount": 125000,
    "currency": "MXN",
    "voucher": {
      "barcode": "646180123456789012",
      "digitable_line": "646180123456789012",
      "url": "https://provider.example/pay/order_3001",
      "expiration_date": "2026-05-12T23:59:59.000Z",
      "instructions": "Pague usando a referência bancária antes do vencimento.",
      "receipt_url": null
    }
  }
}

​
Resposta de ACK

{
  "received": true
}

​
Eventos emitidos hoje

  • transaction.created
  • transaction.pending
  • transaction.paid
  • transaction.cancelled
  • transaction.refunded
  • transaction.partially_refunded
  • transaction.chargedback
  • transaction.three_ds_required

​
Erro comum de ingestão

{
  "error": "missing_event_id"
}
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.