> For the complete documentation index, see [llms.txt](https://docs.barte.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.barte.com/api-reference/estorno/estorno-cobranca-novo-fluxo.md). # 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). {% openapi src="/files/Slz8Ol2eYCu0a9im6MwD" path="/v2/charges/{uuid}/refunds" method="post" %} [charges-refund-novo-fluxo.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-e63e3812f535c3c03d86e95a48409c4ce4bb9eb2%2Fcharges-refund-novo-fluxo.yaml?alt=media) {% endopenapi %} ## 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)](https://docs.barte.com/guias/webhooks/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](https://docs.barte.com/guias/webhooks/webhooks-overview/webhook-v2-visao-geral), com o array `refunds[]` de [Campos do Webhook v2](https://docs.barte.com/guias/webhooks/webhooks-overview/webhook-v2-visao-geral/webhook-v2-campos#estrutura-de-refunds). {% hint style="warning" %} 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. {% endhint %} ## 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. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.barte.com/api-reference/estorno/estorno-cobranca-novo-fluxo.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.