Eventos de cobrança

Os eventos de cobrança são enviados no formato v2 para as cobranças de pedidos criados por POST /v2/orders e das faturas de assinaturas criadas por POST /v2/subscriptions. A cobrança de um recurso criado pela v1 gera os mesmos eventos, mas no formato v1 — inclusive charge.expired e charge.canceled.

Evento	Quando acontece
`charge.created`	A cobrança foi criada
`charge.pending`	A cobrança está pendente
`charge.paid`	A cobrança foi paga
`charge.failed`	A cobrança falhou
`charge.reproved`	A cobrança foi reprovada
`charge.refunded`	A cobrança foi totalmente estornada
`charge.partial_refunded`	A cobrança foi parcialmente estornada
`charge.chargeback`	A cobrança recebeu chargeback
`charge.expired`	A cobrança expirou (por exemplo, PIX não pago)
`charge.canceled`	A cobrança foi cancelada

Em uma assinatura, a cobrança paga de uma fatura gera invoice.paid, e não charge.paid. O estorno de uma cobrança de fatura gera charge.refunded ou charge.partial_refunded.

charge.challenged não existe no formato v2. Ele é entregue no formato v1, mesmo para cobranças de recursos criados pela v2.

Payload

Diferente dos demais eventos, o data dos eventos de cobrança não é o objeto de GET /v2/charges/{id}. Ele traz um payload próprio, com dados do cliente, do cartão e da transação:

charge.paid

{
  "id": "hook_Lm3Nb7Vc1Xz5Qw9e",
  "type": "charge.paid",
  "webhook_version": "v2",
  "created_at": "2026-09-14T15:04:05Z",
  "data": {
    "id": "5d1c9a7e-2b4f-4e8a-9c3d-7f6e5a4b3c2d",
    "code": "cha_8Kq2Lm9XvB3nT7pZ",
    "status": "paid",
    "amount": 10000,
    "amount_refunded": 0,
    "currency": "brl",
    "original_amount": 10000,
    "original_currency": "brl",
    "exchange_rate": null,
    "payment_method": "credit_card",
    "installments": 1,
    "created_at": "2026-09-14T15:00:00Z",
    "order": {
      "id": "8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d",
      "code": "ord_7Hk2Pq9Xm4Ln8Rt3"
    },
    "customer": {
      "id": "3f2e1d0c-9b8a-4c7d-8e6f-5a4b3c2d1e0f",
      "code": "cli_abc123",
      "name": "João Silva",
      "email": "joao@exemplo.com.br"
    },
    "card": {
      "brand": "visa",
      "first_six": "411111",
      "last_four": "1111",
      "holder_name": "João Silva",
      "exp_month": 12,
      "exp_year": 2030
    },
    "transaction": {
      "nsu": "123456",
      "tid": "10017348980735271001",
      "acquirer_message": "Transação autorizada"
    }
  }
}

Campo	Tipo	Descrição
`id`	string	Identificador interno da cobrança
`code`	string	Identificador da cobrança na API. Use em `GET /v2/charges/{id}`
`status`	string	Status da cobrança no webhook (veja abaixo)
`amount`	integer	Valor cobrado, em centavos de real
`amount_refunded`	integer	Total já estornado, em centavos de real. `0` quando não houve estorno
`currency`	string	Sempre `brl`
`original_amount`	integer	Valor na moeda enviada, em centavos. Igual a `amount` em BRL
`original_currency`	string	Moeda enviada, em minúsculas (`brl`, `usd`)
`exchange_rate`	number \| null	Cotação usada (1 unidade da moeda enviada = `exchange_rate` reais). `null` em BRL
`payment_method`	string	`credit_card`, `pix` ou `boleto`
`installments`	integer	Número de parcelas
`created_at`	string	Data de criação da cobrança (ISO 8601, UTC)
`order.id`	string	Identificador interno do pedido
`order.code`	string	Identificador do pedido na API. Use em `GET /v2/orders/{id}` ou `GET /v2/invoices/{id}`
`customer`	object \| null	`id`, `code`, `name` e `email` do cliente
`card`	object \| null	`brand`, `first_six`, `last_four`, `holder_name`, `exp_month` e `exp_year`. `null` quando a cobrança não tem cartão vinculado
`transaction.nsu`	string \| null	NSU da transação
`transaction.tid`	string \| null	TID da transação
`transaction.acquirer_message`	string \| null	Mensagem retornada pela adquirente, quando houver

O vocabulário do webhook de cobrança é diferente do da API: aqui o método é credit_card (na API, card) e o estorno parcial é partial_refunded (na API, partially_refunded).

Sem cartão vinculado, o webhook envia "card": null. Nas respostas da API (GET /v2/charges/{id} e payments[] de pedidos e faturas), a chave card não aparece. Trate os dois casos no seu código. O id do cartão não é enviado.

Status da cobrança no webhook

`status`	Significado
`created`	Criada
`pending`	Pendente
`processing`	Em processamento
`authorized`	Autorizada, aguardando captura
`challenged`	Aguardando verificação por código
`paid`	Paga
`failed`	Falhou ou foi reprovada
`expired`	Expirada
`canceled`	Cancelada
`voided`	Autorização desfeita
`refunded`	Totalmente estornada
`partial_refunded`	Parcialmente estornada
`chargeback`	Chargeback

​Payload

​Status da cobrança no webhook

Payload

Status da cobrança no webhook