> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autorizou.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar Estorno

> Estornar total ou parcialmente um pagamento autorizado

Este endpoint estorna pagamentos, com suporte a estorno **total** e **parcial**. Quando a venda tem
split, a reversão das fatias acontece automaticamente no motor financeiro, respeitando o que cada
participante ainda deve devolver.

## Parâmetros

<ParamField body="payment_id" type="string" required>
  UUID do pagamento a estornar.
</ParamField>

<ParamField body="amount" type="integer">
  Valor a estornar, em **centavos**. Omitido = estorno **total do remanescente** (o servidor usa o
  valor exato, sem risco de arredondamento). Informado = estorno **parcial**.

  O valor **não pode exceder o remanescente reembolsável** (valor original menos estornos já
  solicitados/concluídos). Acima disso a API rejeita com `422` — nunca ajusta por conta própria.
</ParamField>

<ParamField body="reason" type="string">
  Motivo do estorno (texto livre, para seu controle).
</ParamField>

<ParamField body="bank_account" type="object">
  **Obrigatório quando o pagamento é boleto** (`bank_slip`): a conta que recebe a devolução.

  <Expandable title="Estrutura da conta bancária">
    <ParamField body="bank_account.holder_name" type="string" required>Nome do titular (máx. 255)</ParamField>
    <ParamField body="bank_account.holder_type" type="string" required>Tipo do documento do titular: `cpf` ou `cnpj`</ParamField>
    <ParamField body="bank_account.holder_document" type="string" required>Documento do titular (apenas dígitos)</ParamField>
    <ParamField body="bank_account.bank" type="string" required>Código do banco (ex.: `341`)</ParamField>
    <ParamField body="bank_account.branch_number" type="string" required>Agência (máx. 13)</ParamField>
    <ParamField body="bank_account.branch_check_digit" type="string" required>Dígito da agência (máx. 2)</ParamField>
    <ParamField body="bank_account.account_number" type="string" required>Número da conta (máx. 13)</ParamField>
    <ParamField body="bank_account.account_check_digit" type="string" required>Dígito da conta (máx. 2)</ParamField>
  </Expandable>
</ParamField>

## Pré-requisitos

* O pagamento precisa estar **`authorized`** ou **`refunded_partially`**. Qualquer outro status é
  rejeitado com `422`.
* O pagamento precisa pertencer à **sua conta** (a chave usada). Pagamento de outro lojista responde `404`.

## Exemplos de Requisição

<CodeGroup>
  ```bash cURL - Estorno Total theme={null}
  curl -X POST https://pay.autorizou.dev/api/v1/refunds \
    -H "Authorization: Bearer SUA_CHAVE" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_id": "b81f4c26-5d9e-4f7a-8c3b-2e6a9d4f1b58"
    }'
  ```

  ```bash cURL - Estorno Parcial theme={null}
  curl -X POST https://pay.autorizou.dev/api/v1/refunds \
    -H "Authorization: Bearer SUA_CHAVE" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_id": "b81f4c26-5d9e-4f7a-8c3b-2e6a9d4f1b58",
      "amount": 5000,
      "reason": "Item com defeito"
    }'
  ```

  ```bash cURL - Estorno de Boleto theme={null}
  curl -X POST https://pay.autorizou.dev/api/v1/refunds \
    -H "Authorization: Bearer SUA_CHAVE" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_id": "e4a7c158-9b2d-4e6f-a831-6c9e2b5d8f47",
      "bank_account": {
        "holder_name": "João Silva",
        "holder_type": "cpf",
        "holder_document": "12345678901",
        "bank": "341",
        "branch_number": "1234",
        "branch_check_digit": "5",
        "account_number": "67890",
        "account_check_digit": "1"
      }
    }'
  ```
</CodeGroup>

## Resposta (201 Created)

```json theme={null}
{
  "id": "5f2e8b91-4c7d-4a3e-96b5-8d1f4e7a2c60",
  "payment_id": "b81f4c26-5d9e-4f7a-8c3b-2e6a9d4f1b58",
  "amount": 5000,
  "status": "requested",
  "type": "partial",
  "created_at": "2024-01-15 14:20:00"
}
```

<ResponseField name="id" type="string">UUID do estorno criado.</ResponseField>

<ResponseField name="payment_id" type="string">UUID do pagamento estornado.</ResponseField>

<ResponseField name="amount" type="integer">Valor estornado em centavos.</ResponseField>

<ResponseField name="status" type="string">
  Status do estorno. Nasce **`requested`** e evolui de forma assíncrona.

  **Valores:** `requested`, `scheduled`, `success`, `failed`, `canceled`
</ResponseField>

<ResponseField name="type" type="string">
  Derivado pelo servidor a partir do valor: **`full`** quando o valor cobre todo o remanescente,
  **`partial`** caso contrário.
</ResponseField>

## Acompanhamento

O estorno é processado de forma **assíncrona** junto ao emissor. Acompanhe pelo webhook
(`payment.refunded` quando concluído; o pagamento vai a `refunded` ou `refunded_partially`) ou por
polling em `GET /payments/{id}`.

<Info>
  **Estornos parciais em sequência:** o remanescente reembolsável considera o valor **original** da
  venda menos tudo que já foi solicitado. Você pode estornar parcialmente várias vezes até zerar; o
  estorno "total" após parciais devolve exatamente o que resta.
</Info>

## Códigos de Erro

<AccordionGroup>
  <Accordion title="422 - Status inválido" icon="circle-xmark">
    ```json theme={null}
    {
      "message": "O pagamento deve estar Autorizado ou Parcialmente Reembolsado para ser reembolsado",
      "errors": { "payment_id": ["O pagamento deve estar Autorizado ou Parcialmente Reembolsado para ser reembolsado"] }
    }
    ```
  </Accordion>

  <Accordion title="422 - Valor acima do remanescente" icon="circle-xmark">
    ```json theme={null}
    {
      "message": "O valor não pode exceder o valor reembolsável restante.",
      "errors": { "amount": ["O valor não pode exceder o valor reembolsável restante."] }
    }
    ```
  </Accordion>

  <Accordion title="422 - Conta bancária ausente (boleto)" icon="circle-xmark">
    ```json theme={null}
    {
      "message": "Conta bancária é obrigatória para boleto",
      "errors": { "bank_account": ["Conta bancária é obrigatória para boleto"] }
    }
    ```
  </Accordion>

  <Accordion title="404 - Pagamento não encontrado" icon="circle-xmark">
    O `payment_id` não existe **ou pertence a outro lojista** (o escopo por conta responde 404, nunca
    vaza a existência do recurso).
  </Accordion>
</AccordionGroup>