Estornar Cobrança

Visão geral

O mesmo fluxo de estorno atende cobranças de cartão de crédito, cartão de débito, PIX, Google Pay e Apple Pay; boleto não tem suporte a estorno. O processamento é assíncrono: o 202 Accepted da criação confirma apenas que a Barte aceitou o pedido, não que o dinheiro já voltou ao comprador.

Suporta estorno total e parcial: o mesmo endpoint aceita qualquer valor entre R$ 0,01 e o saldo restante da cobrança. Uma cobrança pode receber múltiplos estornos parciais, até zerar o saldo.

A resposta 202 retorna o estorno recém-criado (uuid, status, amount, createdAt, idempotencyKey, errorReason). Guarde o uuid: ele identifica esse estorno individual nos webhooks e no array refunds[] da cobrança, o que importa especialmente quando há múltiplos estornos parciais na mesma cobrança. Numa criação nova errorReason vem sempre nulo — ele só aparece preenchido no replay de idempotência descrito abaixo.

A criação exige o header x-idempotency-key, com a mesma semântica create-or-retrieve já usada em Order, Subscription e Transfer: reenviar a mesma chave para a mesma cobrança devolve o estorno já criado em vez de duplicar. Use um identificador seu, único por pedido de estorno e de no máximo 63 caracteres. Além de proteger contra retries de rede, é ele que permite correlacionar os eventos de webhook com a sua requisição. Duas situações de conflito retornam 409: reenviar a mesma chave com um amount diferente (BAR-0466), ou uma segunda chamada com a mesma chave chegando enquanto a primeira ainda está em voo (BAR-0467). No replay bem-sucedido, a resposta reflete o estado atual daquele estorno — se ele já tiver concluído com falha entre as duas chamadas, é assim que errorReason aparece preenchido na resposta de criação.

O pedido de estorno precisa ser feito dentro da janela contada a partir do pagamento: 90 dias para PIX e 180 dias para cartão de crédito, cartão de débito, Google Pay e Apple Pay (ver BAR-0434 na tabela de erros).

Solicitar estorno (total ou parcial)

post

/v2/charges/{uuid}/refunds

Solicita o estorno, total ou parcial, de uma cobrança em cartão de crédito, cartão de débito, PIX, Google Pay ou Apple Pay. O processamento é ASSÍNCRONO: o 202 confirma apenas que o pedido foi aceito, não que o dinheiro já voltou ao comprador. Ver a página "Estornar Cobrança (novo fluxo)" para o significado de cada estado intermediário e o tempo esperado de conclusão.

Authorizations

X-Token-ApistringRequired

Token de autenticação para acesso à API

Path parameters

uuidstring · uuidRequired

UUID da cobrança a ser estornada

Header parameters

X-Token-ApistringRequired

Token de autenticação para acesso à API

Content-Typestring · enumRequiredPossible values:

x-idempotency-keystring · max: 63Required

Chave de idempotência definida por você, com semântica create-or-retrieve: reenviar a mesma chave para a mesma cobrança devolve o estorno já criado em vez de criar um novo. Protege contra retries de rede e é o valor que permite correlacionar os eventos de webhook com a sua requisição. Use um identificador único por pedido de estorno, de no máximo 63 caracteres.

Body

amountnumber · double · min: 0.01Required

Valor a estornar. Use o valor total da cobrança para estorno total, ou um valor menor para estorno parcial.

Example: 150

Responses

202

Solicitação de estorno aceita para processamento assíncrono. O corpo retorna o estorno recém-criado; guarde o uuid para correlacionar com webhooks e com o array refunds[] da cobrança.

application/json

uuidstring · uuidOptional

Identificador do estorno individual recém-criado.

Example: 7d8f2a30-1c5e-4b9a-8f21-3e9a6d4c5b10

statusstringOptional

Status inicial do estorno.

Example: PROCESSING

amountnumberOptional

Valor solicitado do estorno.

Example: 25

createdAtstring · date-timeOptional

Data e hora de criação do pedido de estorno, ISO 8601 UTC, precisão de segundos.

Example: 2026-08-25T14:30:12Z

idempotencyKeystringOptional

Chave enviada no header x-idempotency-key, ecoada de volta. Omitida quando o estorno foi criado sem a chave.

Example: 3a1f8e2c-9d47-4b60-a815-2f7c5e9b1d04

errorReasonstringOptional

Motivo de falha, quando houver. Numa criação nova vem sempre nulo; só aparece preenchido no replay de idempotência de um estorno que já concluiu com falha. Omitido quando nulo.

400

Requisição rejeitada. Ver a tabela de códigos de erro na página "Estornar Cobrança (novo fluxo)" para o significado de cada BAR-0XXX.

application/json

401

Token inativo ou inexistente

application/json

403

Acesso negado

application/json

409

Conflito de idempotência: a mesma x-idempotency-key foi reenviada com um amount diferente (BAR-0466), ou já existe uma requisição em andamento com a mesma chave (BAR-0467).

application/json

429

Muitas requisições

application/json

500

Erro interno do servidor

application/json

post/v2/charges/{uuid}/refunds

POST /v2/charges/{uuid}/refunds HTTP/1.1
Host: api.barte.com
X-Token-Api: text
x-idempotency-key: text
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "amount": 150
}

{
  "uuid": "7d8f2a30-1c5e-4b9a-8f21-3e9a6d4c5b10",
  "status": "PROCESSING",
  "amount": 25,
  "createdAt": "2026-08-25T14:30:12Z",
  "idempotencyKey": "3a1f8e2c-9d47-4b60-a815-2f7c5e9b1d04",
  "errorReason": "text"
}

Tempo esperado de conclusão

Na maioria dos casos o estorno é concluído em poucos segundos. Em cartão, quando a cobrança ainda não liquidou, o estorno é um simples cancelamento (void) da autorização, sem depender do prazo do adquirente. Em PIX, a devolução é enviada ao provedor de pagamento assim que o pedido é aceito.

Quando o provedor não confirma na primeira tentativa, a Barte aplica uma régua de retentativas com espaçamento crescente, igual para todos os métodos de pagamento e provedores: a primeira tentativa é imediata e, em caso de falha, novas tentativas ocorrem ao longo de até 48 horas. Se a régua se esgota com uma rejeição confirmada do provedor, o estorno é marcado como falho. Se a última falha é incerta (por exemplo, indisponibilidade momentânea do provedor), o estorno permanece em processamento aguardando a confirmação definitiva, sem prazo garantido.

Webhook

O fluxo de estorno notifica por dois caminhos complementares:

• Domínio CHARGE (Webhook v2). Três tipos de evento por estorno individual — charge.refund.processing, charge.refund.succeeded e charge.refund.failed —, incluindo estornos parciais que não zeram o saldo. O payload traz o uuid do estorno individual, o mesmo retornado na criação, permitindo correlacionar cada evento ao seu estorno mesmo com múltiplos parciais na mesma cobrança. Documentação na página Estornos (CHARGE).

• Evento order.refund do domínio ORDER. Quando o estorno zera o saldo restante da cobrança (total, ou a soma de parciais que chega a zero), o pedido transiciona para REFUND e dispara o evento já documentado em Webhook v2, com o array refunds[] de Campos do Webhook v2.

Sem o domínio CHARGE ativo, um estorno parcial que não zera o saldo da cobrança não dispara webhook nenhum: o pedido não muda de status. A cobertura do CHARGE também é progressiva (só estornos do fluxo novo geram eventos), ver o aviso de cobertura na própria página.

Erros

Erros de validação da criação retornam 400; conflitos de idempotência retornam 409. O corpo segue o mesmo formato em ambos os casos.

Código	Status	Quando acontece	O que fazer
BAR-0424	400	UUID de cobrança não existe, ou não pertence à conta autenticada.	Conferir o UUID e a conta usada no token.
BAR-0434	400	Fora do prazo máximo de estorno (90 dias para PIX, 180 para os demais métodos), ou a cobrança ainda não tem data de pagamento confirmada (a mensagem pode aparecer como "0 dias" nesse segundo caso).	Se a cobrança não tem paidDate, aguardar a confirmação do pagamento. Se o prazo real expirou, não há retentativa possível.
BAR-0450	400	Status atual da cobrança não permite estorno (ex.: já cancelada, em disputa ou chargeback). Uma cobrança já totalmente estornada pode responder este código ou o BAR-0451.	Conferir o status atual da cobrança antes de reenviar.
BAR-0451	400	Valor solicitado é maior que o saldo restante da cobrança, inclusive quando o saldo já está zerado.	Reduzir o valor ou consultar o saldo restante antes de reenviar.
BAR-0452	400	Método de pagamento não suporta estorno (ex.: boleto).	Não tentar novamente — método sem suporte.
BAR-0460	400	Saldo futuro agregado da conta é insuficiente para cobrir o estorno líquido de impostos.	Verificar saldo da conta, não da cobrança individual.
BAR-0463	400	Estorno bloqueado por política (risco/fraude/suspensão administrativa).	Contatar o suporte Barte — não é algo que o integrador resolve sozinho.
BAR-0466	409	A mesma x-idempotency-key foi reenviada nesta cobrança com um amount diferente do da primeira chamada.	Usar uma chave nova, ou reenviar com o mesmo amount da primeira chamada.
BAR-0467	409	Já existe uma requisição em andamento com a mesma x-idempotency-key para esta cobrança.	Aguardar a resposta da primeira chamada antes de reenviar.
BAR-0500	400	amount ausente ou menor que 0.01.	Corrigir o valor enviado.