Acompanhar reembolsos e chargebacks

Receba o pedido de reembolso

Quando o cliente pede reembolso, a PagPolar envia TRANSACTION_ASK_REFUNDING para o seu webhook. O dinheiro ainda não voltou para o cliente.

Exemplo resumido do que chega. O payload completo está em TRANSACTION_ASK_REFUNDING.

{
  "event": "TRANSACTION_ASK_REFUNDING",
  "data": {
    "transaction": {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "identifier": "PPO9876543210",
      "status": "ASK_REFUND",
      "payment_method": "PIX",
      "total_amount": "197.0000",
      "refund_reason": "Produto não atendeu às expectativas",
      "refund_at": null
    }
  }
}

O status da venda diz o tipo de pedido:

Faça assim:

1. Grave o pedido junto da venda, usando o data.transaction.id.
2. Guarde o data.transaction.identifier. É o código da venda, com o prefixo, como PPO9876543210: o mesmo valor da API. Use esse valor no filtro sale_identifier do próximo passo.
3. Não revogue o acesso ainda. Espere TRANSACTION_REFUNDED.

Consulte o pedido na API

Chame GET /refunds com o código da venda no filtro sale_identifier.

curl "https://api.pagpolar.com/v1/refunds?sale_identifier=PPO9876543210" \
  -H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>"

const apiUrl = 'https://api.pagpolar.com/v1';
const accessToken = '<SEU_TOKEN_DE_ACESSO>';
const saleIdentifier = 'PPO9876543210';

const query = new URLSearchParams({ sale_identifier: saleIdentifier });

const response = await fetch(`${apiUrl}/refunds?${query}`, {
  headers: { Authorization: `Bearer ${accessToken}` },
});

if (!response.ok) {
  throw new Error(`Erro ${response.status}: ${await response.text()}`);
}

const body = await response.json();

for (const refund of body.data) {
  console.log(refund.id, refund.status, refund.is_partial, refund.refund_amount);
}

Resposta resumida. Todos os campos estão na referência de GET /refunds.

{
  "data": [
    {
      "id": "3c9f1e2a-7b4d-4e8a-9f10-2b3c4d5e6f70",
      "status": "PENDING",
      "requested_by": "CLIENT",
      "is_partial": false,
      "refund_amount": null,
      "reason": "Não atendeu às expectativas",
      "refused_reason": null,
      "canceled_reason": null,
      "return_tracking": null,
      "sale": {
        "identifier": "PPO9876543210",
        "status": "ASK_REFUND",
        "payment_method": "PIX",
        "total_amount": 197
      },
      "created_at": "2026-09-15T13:00:00.000Z",
      "updated_at": "2026-09-15T13:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}

Filtros aceitos:

O bloco sale não traz o id da venda. Para ver a venda completa, chame GET /sales/{identifier} com o sale.identifier.

Uma venda só tem um pedido em andamento por vez. Depois que um pedido termina (reembolsado, recusado, cancelado ou com falha), um novo pedido pode ser aberto. Por isso, o filtro pode trazer mais de um pedido para a mesma venda.

Acompanhe a decisão no painel

O vendedor responde ao pedido no painel. Nenhuma decisão envia evento de webhook, nem quando a venda volta para PAID. Consulte GET /refunds para saber o que aconteceu. Veja Ciclo de vida da venda.

No painel, os pedidos ficam em Vendas → Reembolsos, com os indicadores por situação e a lista de pedidos:

Ao abrir um pedido, a tela Detalhes do reembolso mostra a situação, a compra, o motivo informado pelo cliente e, quando houver, a data e o motivo da recusa. É nessa tela que o vendedor aceita ou recusa um pedido pendente:

Na recusa do pedido da venda inteira, o repasse e a taxa ligados à venda também voltam para PAID. Para saber se o pedido foi recusado ou cancelado, use o status do pedido em GET /refunds, e não o status da venda.

A API não mostra o motivo da falha do estorno. O pedido aparece só como FAILED.

Reaja ao estorno

Quando o gateway confirma o estorno, a venda muda de status e a PagPolar envia um evento. O que chega depende do caso:

"Contava como paga" quer dizer: a venda estava em PAID, REFUNDING, ASK_REFUND, ASK_PARTIAL_REFUND ou CHARGEBACK_APPROVED.

Exemplo resumido de TRANSACTION_REFUNDED:

{
  "event": "TRANSACTION_REFUNDED",
  "data": {
    "transaction": {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "identifier": "PPO9876543210",
      "status": "REFUNDED",
      "payment_method": "PIX",
      "total_amount": "197.0000",
      "refund_reason": "Produto não atendeu às expectativas"
    }
  }
}

Ao receber TRANSACTION_REFUNDED:

1. Confira o data.transaction.status. Se já for REFUNDED no seu sistema, ignore.
2. Revogue o acesso ao que foi vendido.
3. Marque o pedido como reembolsado.

Ao receber TRANSACTION_CANCELED depois de um pedido de reembolso, cancele o pedido no seu sistema.

Para saber o valor devolvido no estorno de um item sem evento, consulte GET /refunds?status=REFUNDED e leia is_partial e refund_amount.