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 (o PIX nasce aqui, com `status: "pending"`).
`transaction_paid`	O pagamento é confirmado (`status: "paid"`). É o gatilho para liberar o pedido.
`transaction_updated`	Notifica uma mudança de status da transação (ex.: passou a `refused`).
`transaction_refunded`	Um estorno é concluído (`status: "refund"`).
`refund_requested`	O comprador pede o estorno. O dinheiro ainda não saiu — veja Nos dois eventos de reembolso.
`card_declined`	Uma cobrança no cartão foi recusada pelo processador.

Payload dos eventos `transaction_*`

transaction_paid
transaction_created
transaction_updated
transaction_refunded
refund_requested

{
  "id": "9f1c8e2a-2b7d-4c1a-9f3e-uuid",
  "type": "transaction",
  "event": "transaction_paid",
  "scope": "user",
  "transaction": {
    "id": "clxabc123def456",
    "amount": 19700,
    "netAmount": 18200,
    "status": "paid",
    "pix": {
      "endToEndId": "E12345678202606031200abcdef0001",
      "payerInfo": { "name": "Maria Silva", "cpf": "***456789**" }
    },
    "paidAt": "2026-09-07T13:10:42.000Z",
    "refundPeriodDays": 15,
    "refundDeadline": "2026-09-22T23:59:59-03:00"
  },
  "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": 19700,
    "netAmount": 18200,
    "status": "pending",
    "pix": { "endToEndId": null, "payerInfo": null },
    "paidAt": null,
    "refundPeriodDays": null,
    "refundDeadline": 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_updated",
  "scope": "user",
  "transaction": {
    "id": "clxabc123def456",
    "amount": 19700,
    "netAmount": 18200,
    "status": "waiting",
    "pix": { "endToEndId": null, "payerInfo": null },
    "paidAt": null,
    "refundPeriodDays": null,
    "refundDeadline": null
  },
  "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" }
}

Este exemplo mostra uma atualização antes do pagamento (paidAt, refundPeriodDays e refundDeadline nulos). Se a mudança de status acontecer depois do pagamento — por exemplo, uma recusa de estorno — os três campos vêm preenchidos, como em transaction_paid.

{
  "id": "9f1c8e2a-2b7d-4c1a-9f3e-uuid",
  "type": "transaction",
  "event": "transaction_refunded",
  "scope": "user",
  "transaction": {
    "id": "clxabc123def456",
    "amount": 19700,
    "netAmount": 18200,
    "status": "refund",
    "paidAt": "2026-09-07T13:10:42.000Z",
    "refundPeriodDays": 15,
    "refundDeadline": "2026-09-22T23:59:59-03:00",
    "refundRequestedAt": "2026-09-19T20:33:11.000Z",
    "refundedAt": "2026-09-20T14:02:57.000Z"
  },
  "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": "refund_requested",
  "scope": "user",
  "transaction": {
    "id": "clxabc123def456",
    "amount": 19700,
    "netAmount": 18200,
    "status": "paid",
    "paidAt": "2026-09-07T13:10:42.000Z",
    "refundPeriodDays": 15,
    "refundDeadline": "2026-09-22T23:59:59-03:00",
    "refundRequestedAt": "2026-09-19T20:33:11.000Z",
    "refundedAt": null
  },
  "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" }
}

refundedAt vem nulo aqui — o comprador pediu o estorno, mas o dinheiro ainda não saiu. status continua "paid" até o estorno ser executado, momento em que você recebe transaction_refunded com refundedAt preenchido.

Prazo de reembolso e datas do pagamento

Os cinco eventos acima carregam, dentro do bloco transaction, o relógio do prazo de reembolso:

string | null

Quando o pagamento foi aprovado, em ISO 8601 UTC (ex.: 2026-09-07T13:10:42.000Z). É de onde a contagem do prazo parte. Vem nulo em transaction_created e em qualquer evento de uma compra que ainda não foi paga — o relógio ainda não começou.

number | null

O prazo de reembolso, em dias, que o produto principal tinha vigente no dia do pagamento: 7, 15 ou 30. Vem nulo junto com paidAt antes do pagamento.

string | null

O instante em que o prazo de reembolso termina: sempre às 23:59:59 no fuso de Brasília, com o deslocamento explícito no próprio valor — por exemplo 2026-09-22T23:59:59-03:00. Não adivinhe o fuso a partir de outro campo: use o deslocamento que vem no valor. Vem nulo antes do pagamento, junto com paidAt e refundPeriodDays.

Nos dois eventos de reembolso

refund_requested e transaction_refunded ganham mais dois campos, no mesmo bloco transaction:

string

Quando o comprador abriu o pedido de estorno, em ISO 8601 UTC. Presente apenas em refund_requested e transaction_refunded.

string | null

Quando o dinheiro efetivamente saiu, em ISO 8601 UTC. Em refund_requested vem nulo — o estorno foi pedido, mas ainda não executado. Em transaction_refunded vem sempre preenchido. Fora desses dois eventos, o campo não aparece no payload.

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.

number

Valor líquido em centavos, já descontadas as taxas.

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.

string | null

Ver Prazo de reembolso e datas do pagamento acima.

number | null

Ver Prazo de reembolso e datas do pagamento acima.

string | null

Ver Prazo de reembolso e datas do pagamento acima.

string

Só em refund_requested/transaction_refunded. Ver acima.

string | null

Só em refund_requested/transaction_refunded. Ver acima.

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". paidAt, refundPeriodDays e refundDeadline vêm nulos.

transaction_paid

O cliente paga e você recebe este evento com status: "paid". Libere o pedido aqui. paidAt, refundPeriodDays e refundDeadline já vêm preenchidos — é o início do prazo de reembolso.

refund_requested (eventual)

Caso o comprador peça o estorno dentro do prazo, você recebe este evento com refundRequestedAt preenchido e refundedAt nulo.

transaction_refunded (eventual)

Quando o estorno é executado, você recebe este evento com refundRequestedAt e refundedAt preenchidos.

Visão geral

Segurança

Eventos

Transações

Payload dos eventos `transaction_*`

Prazo de reembolso e datas do pagamento

Nos dois eventos de reembolso

Campos

Evento `card_declined`

Ciclo de status de uma cobrança

​Payload dos eventos transaction_*

​Prazo de reembolso e datas do pagamento

​Nos dois eventos de reembolso

​Campos

​Evento card_declined

​Ciclo de status de uma cobrança

Payload dos eventos `transaction_*`

Prazo de reembolso e datas do pagamento

Nos dois eventos de reembolso

Campos

Evento `card_declined`

Ciclo de status de uma cobrança