charge.refunded

Enviado quando um estorno é concluído — inclusive os feitos fora do seu fluxo.

WEBHOOK charge.refunded

parcial

{
  "id": "evt_01k1y7c4a1b2c3d4e5f6g7h8i9",
  "type": "charge.refunded",
  "created_at": "2026-08-05T10:12:03+00:00",
  "data": {
    "charge": {
      "object": "charge",
      "id": "ch_01k1y6r6m6q2x0p3d9v4t7c8n2",
      "status": "partially_refunded",
      "payment_method": "pix",
      "amount": 10000,
      "currency": "BRL",
      "platform_fee": 798,
      "net_amount": 9202,
      "refunded_amount": 4000,
      "description": "Curso de Vue 3",
      "reference": "pedido-1042",
      "customer": {
        "name": "João Comprador",
        "email": "[e-mail]",
        "document": "111.***.***-35"
      },
      "pix": {
        "qr_code": "00020101021226840014br.gov.bcb.pix2562qrcodepix.example.com/v2/abcd1234",
        "expires_at": "2026-08-04T15:00:00+00:00",
        "end_2_end_id": "E12345678202608041200"
      },
      "created_at": "2026-08-04T14:00:00+00:00",
      "paid_at": "2026-08-04T14:03:11+00:00",
      "expired_at": null,
      "refunded_at": "2026-08-05T10:12:02+00:00"
    },
    "refund": {
      "object": "refund",
      "id": "rf_01k1y7c3n8b5w2q9r4t6y8u1i3",
      "status": "succeeded",
      "amount": 4000,
      "currency": "BRL",
      "fee_returned": 280,
      "seller_debit": 3720,
      "reason": "Devolução de um item",
      "created_at": "2026-08-05T10:12:00+00:00"
    }
  }
}

Confira a assinatura antes de agir. Ver Verificar a assinatura.

O evento traz a cobrança e o estorno, porque as duas perguntas aparecem juntas do outro lado: quanto voltou (o estorno) e se sobrou algo (a cobrança, com status e refunded_amount já atualizados). Uma venda devolvida pela metade chega como partially_refunded, não refunded.

Authorizations

Authorization · string · header · required

Chave secreta do vendedor, criada no painel em Desenvolvedores.

O valor em claro existe uma única vez, na criação. Guardamos só o hash SHA-256 - nem o suporte consegue recuperá-lo, o que é o ponto: um dump do nosso banco não permite cobrar em nome de ninguém.

A chave vai no servidor. Colocá-la no navegador do comprador a entrega a qualquer pessoa que abra a página.

Headers

X-Vext-Signature · string · required

Assinatura da entrega, no formato t=<timestamp>,v1=<hmac>, onde hmac é HMAC-SHA256("<timestamp>.<corpo bruto>", <segredo>).

Duas regras ao conferir:

1. Calcule sobre o corpo bruto, antes de desserializar. Reserializar muda espaçamento e ordem, e o HMAC deixa de bater.
2. Recuse timestamps com mais de 5 minutos. É isso que impede alguém que interceptou uma entrega de charge.paid de reenviá-la quantas vezes quiser, com assinatura perfeitamente válida.

Pattern: ^t=[0-9]+,v1=[0-9a-f]{64}$

X-Vext-Event · string · required

Tipo do evento, repetido fora do corpo. Redundante com o payload e útil mesmo assim: permite filtrar no seu log sem desserializar nada.

X-Vext-Delivery · string · required

Identificador da entrega. Cite-o ao abrir um chamado - é por ele que localizamos a tentativa, a resposta do seu servidor e o horário.

Body

application/json

id · string · required

Identificador do evento. Estável entre as retentativas da mesma entrega - use-o para deduplicar do seu lado.

Example:

"evt_01k1y6r7z2m4n6p8q0r2s4t6u8"

type · enum<string> · required

Available options: charge.paid, charge.refunded, withdrawal.paid

created_at · string<date-time> · required

data · object · required

Show child attributes

Response

200

Recebido.