Referência de eventos

Todo webhook chega como POST com Content-Type: application/json e este envelope:

{
  "id": "e2a1c9d4-5b6f-4a7b-8c9d-0e1f2a3b4c5d",
  "type": "payment.succeeded",
  "created_at": "2026-09-08T13:15:00.000Z",
  "data": {}
}

string

Identificador único do evento (UUID). Use-o para descartar entregas duplicadas.

string

O tipo do evento — um dos listados abaixo.

string

Data/hora em que o evento foi gerado, em ISO 8601 (UTC).

object

Os dados do evento. É um objeto próprio do webhook — não é o objeto de recurso completo que a API REST devolve. Os campos estão descritos abaixo.

Em data, amount_minor é uma string (ex. "49900"), diferente das respostas da API REST, onde valores monetários são inteiros.

`data` — campos

Os três eventos de pagamento carregam o mesmo conjunto de campos.

string

ID do pagamento.

string

ID do checkout que originou o pagamento.

string | null

Cliente vinculado ao checkout, ou null se não havia um.

string

Valor do pagamento na unidade menor da moeda (centavos), como string.

string

Moeda ISO 4217, ex. BRL.

string

pix ou card.

string

Presente apenas em payment.failed. Motivo da recusa, conforme reportado pelo processador (ex. failed, with_error).

payment.succeeded

O pagamento foi confirmado. Libere o pedido.

{
  "id": "e2a1c9d4-5b6f-4a7b-8c9d-0e1f2a3b4c5d",
  "type": "payment.succeeded",
  "created_at": "2026-09-08T13:15:00.000Z",
  "data": {
    "payment_id": "pay_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "checkout_session_id": "checkout_7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b0c",
    "customer_id": "cus_9b2c4f1a-3d5e-4a7b-8c9d-1e2f3a4b5c6d",
    "amount_minor": "49900",
    "currency": "BRL",
    "payment_method": "pix"
  }
}

payment.failed

O pagamento foi recusado. O checkout continua open — o comprador ainda pode gerar uma nova cobrança na mesma sessão.

{
  "id": "b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
  "type": "payment.failed",
  "created_at": "2026-09-08T13:16:00.000Z",
  "data": {
    "payment_id": "pay_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "checkout_session_id": "checkout_7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b0c",
    "customer_id": "cus_9b2c4f1a-3d5e-4a7b-8c9d-1e2f3a4b5c6d",
    "amount_minor": "49900",
    "currency": "BRL",
    "payment_method": "card",
    "failure_code": "with_error"
  }
}

payment.chargedback

Um chargeback foi registrado para um pagamento já confirmado. Reverta a liberação do pedido.

{
  "id": "c0d1e2f3-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
  "type": "payment.chargedback",
  "created_at": "2026-09-20T09:00:00.000Z",
  "data": {
    "payment_id": "pay_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "checkout_session_id": "checkout_7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b0c",
    "customer_id": "cus_9b2c4f1a-3d5e-4a7b-8c9d-1e2f3a4b5c6d",
    "amount_minor": "49900",
    "currency": "BRL",
    "payment_method": "pix"
  }
}

​data — campos

​payment.succeeded

​payment.failed

​payment.chargedback

`data` — campos

payment.succeeded

payment.failed

payment.chargedback