Transações

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

string

UUID da entrega (não é o ID da transação). Use-o para garantir idempotência.

string

Nome do evento. Use este campo para rotear o tratamento no seu sistema.

string

Origem do webhook: user (um webhook que você cadastrou) ou postback (a postbackUrl informada na cobrança).

object

Show propriedades

string

ID da transação.

number

Valor em centavos.

string

Status atual. Veja Status e erros.

string

Motivo da recusa. Presente apenas quando existe.

object

Dados do PIX (endToEndId, payerInfo). Presente quando a transação é PIX.

object

Dados do cliente: name, email, phone, document, documentType, purchaseDate.

object

Sua empresa: name, document, documentType.

object

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.

Visão geral

Segurança

Eventos

Transações

Payload dos eventos `transaction_*`

Campos

Evento `card_declined`

Ciclo de status de uma cobrança

​Payload dos eventos transaction_*

​Campos

​Evento card_declined

​Ciclo de status de uma cobrança

Payload dos eventos `transaction_*`

Campos

Evento `card_declined`

Ciclo de status de uma cobrança