Estes são os eventos do dia a dia de uma integração de pagamentos. Todos os eventos transaction_* compartilham o mesmo formato de payload.
| Evento | Disparado quando |
|---|
transaction_created | A cobrança é criada (PIX e boleto nascem aqui, com status: "pending"). |
transaction_paid | O pagamento é confirmado (status: "paid"). É o gatilho para liberar o pedido. |
transaction_refunded | Um estorno é concluído (status: "refund"). |
transaction_updated | Notifica uma mudança de status da transação (ex.: passou a refused). |
card_declined | Uma cobrança no cartão foi recusada pelo processador. |
Payload dos eventos transaction_*
transaction_paid
transaction_created
transaction_refunded
transaction_updated
{
"id": "9f1c8e2a-2b7d-4c1a-9f3e-uuid",
"type": "transaction",
"event": "transaction_paid",
"scope": "user",
"transaction": {
"id": "clxabc123def456",
"amount": 10000,
"status": "paid",
"pix": {
"endToEndId": "E12345678202606031200abcdef0001",
"payerInfo": { "name": "Maria Silva", "cpf": "***456789**" }
}
},
"customer": {
"name": "Maria Silva",
"email": "maria@email.com",
"phone": "+5511999998888",
"document": "12345678909",
"documentType": "cpf",
"purchaseDate": "2026-06-03T12:00:00.000Z"
},
"company": { "name": "Sua Empresa", "document": "11222333000181", "documentType": "cnpj" },
"sale": {
"type": "one_time",
"subscriptionInterval": null,
"renewalType": null,
"mainOfferId": null,
"orderBumpIds": [],
"orderBumpOfferIds": []
}
}
{
"id": "9f1c8e2a-2b7d-4c1a-9f3e-uuid",
"type": "transaction",
"event": "transaction_created",
"scope": "user",
"transaction": {
"id": "clxabc123def456",
"amount": 10000,
"status": "pending",
"pix": { "endToEndId": null, "payerInfo": null }
},
"customer": {
"name": "Maria Silva",
"email": "maria@email.com",
"phone": "+5511999998888",
"document": "12345678909",
"documentType": "cpf",
"purchaseDate": "2026-06-03T12:00:00.000Z"
},
"company": { "name": "Sua Empresa", "document": "11222333000181", "documentType": "cnpj" }
}
{
"id": "9f1c8e2a-2b7d-4c1a-9f3e-uuid",
"type": "transaction",
"event": "transaction_refunded",
"scope": "user",
"transaction": { "id": "clxabc123def456", "amount": 10000, "status": "refund" },
"customer": {
"name": "Maria Silva",
"email": "maria@email.com",
"document": "12345678909",
"documentType": "cpf",
"purchaseDate": "2026-06-03T12:00:00.000Z"
},
"company": { "name": "Sua Empresa", "document": "11222333000181", "documentType": "cnpj" }
}
{
"id": "9f1c8e2a-2b7d-4c1a-9f3e-uuid",
"type": "transaction",
"event": "transaction_updated",
"scope": "user",
"transaction": {
"id": "clxabc123def456",
"amount": 10000,
"status": "refused",
"refuseReason": "INSUFFICIENT_FUNDS"
},
"customer": {
"name": "Maria Silva",
"email": "maria@email.com",
"document": "12345678909",
"documentType": "cpf",
"purchaseDate": "2026-06-03T12:00:00.000Z"
},
"company": { "name": "Sua Empresa", "document": "11222333000181", "documentType": "cnpj" }
}
Campos
UUID da entrega (não é o ID da transação). Use-o para garantir idempotência. Nome do evento. Use este campo para rotear o tratamento no seu sistema.
Origem do webhook: user (um webhook que você cadastrou) ou postback (a postbackUrl informada na cobrança).
Motivo da recusa. Presente apenas quando existe.
Dados do PIX (endToEndId, payerInfo). Presente quando a transação é PIX.
Dados do cliente: name, email, phone, document, documentType, purchaseDate.
Sua empresa: name, document, documentType.
Metadados da venda (tipo, recorrência, ofertas). Para transações criadas via API, vem com os valores padrão (one_time, listas vazias).
O payload contém dados pessoais do pagador (document, payerInfo). Trate-os conforme a LGPD e armazene apenas o necessário.
Evento card_declined
Disparado quando uma cobrança no cartão é recusada. Usa um formato próprio, voltado a recuperação/notificação:
{
"event": "card_declined",
"seller": {
"id": "clxcompany123",
"name": "Sua Empresa",
"email": "contato@suaempresa.com",
"phone": "+5511999990000"
},
"customer": {
"id": "clxcustomer123",
"name": "Maria Silva",
"email": "maria@email.com",
"phone": "+5511999998888",
"buyDate": "2026-06-03T12:00:00.000Z"
},
"products": [
{
"id": "clxproduct123",
"name": "Produto A",
"description": "Descrição do produto",
"quantity": 1,
"unitPrice": 10000,
"amount": 10000,
"tangible": false,
"productId": "clxproduct123"
}
]
}
Ciclo de status de uma cobrança
transaction_created
Você cria a cobrança e recebe este evento quase imediatamente, com status: "pending".
transaction_paid
O cliente paga e você recebe este evento com status: "paid". Libere o pedido aqui.
transaction_refunded (eventual)
Caso haja estorno, você recebe este evento depois.
