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

# POST /payments/pix/refund

> Processar estorno de transação PIX

## Descrição

Processa o estorno (refund) de uma transação PIX que foi paga com sucesso. O estorno pode ser total ou parcial e deve ser solicitado em até 90 dias após o pagamento original.

<Warning>
  **Requisitos para Estorno:**

  * Transação deve estar com status PAID (paga)
  * Prazo máximo de 90 dias após o pagamento
  * Conta deve ter saldo suficiente para o estorno
  * Valor do estorno não pode exceder o valor original
</Warning>

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token JWT obtido no login
</ParamField>

## Request Body

<ParamField body="transaction_id" type="number" required>
  ID da transação PIX a ser estornada (ID interno do sistema)
</ParamField>

<ParamField body="amount" type="number">
  Valor a ser estornado em reais (opcional - se não informado, estorna valor total)

  Exemplo: 50.00 para estornar R\$ 50,00
</ParamField>

<ParamField body="description" type="string">
  Descrição do motivo do estorno (opcional)

  Exemplo: "Cancelamento da compra"
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indica se o estorno foi processado com sucesso
</ResponseField>

<ResponseField name="message" type="string">
  Mensagem de retorno
</ResponseField>

<ResponseField name="transaction" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="number">
      ID da transação
    </ResponseField>

    <ResponseField name="payment_id" type="string">
      ID do pagamento na subadquirente (Firebank)
    </ResponseField>

    <ResponseField name="status" type="number">
      Status da transação (6 = REFUNDED)
    </ResponseField>

    <ResponseField name="amount" type="number">
      Valor original da transação em centavos
    </ResponseField>

    <ResponseField name="refunded_amount" type="number">
      Valor estornado em centavos
    </ResponseField>

    <ResponseField name="refunded_at" type="string">
      Data do estorno (ISO 8601)
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Estorno Total theme={null}
  curl --request POST \
    --url https://api.econpay.com.br/payments/pix/refund \
    --header 'Authorization: Bearer SEU_TOKEN_JWT' \
    --header 'Content-Type: application/json' \
    --data '{
      "transaction_id": 123,
      "description": "Cancelamento da compra"
    }'
  ```

  ```bash Estorno Parcial theme={null}
  curl --request POST \
    --url https://api.econpay.com.br/payments/pix/refund \
    --header 'Authorization: Bearer SEU_TOKEN_JWT' \
    --header 'Content-Type: application/json' \
    --data '{
      "transaction_id": 124,
      "amount": 50.00,
      "description": "Devolução parcial do valor"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.econpay.com.br/payments/pix/refund', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      transaction_id: 123,
      amount: 50.00, // Opcional - omitir para estorno total
      description: 'Cancelamento da compra'
    })
  });

  const refund = await response.json();

  if (refund.success) {
    console.log('Estorno processado:', refund.transaction.id);
    console.log('Valor estornado:', refund.transaction.refunded_amount / 100);
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.econpay.com.br/payments/pix/refund',
      headers={
          'Authorization': f'Bearer {token}',
          'Content-Type': 'application/json'
      },
      json={
          'transaction_id': 123,
          'amount': 50.00,  # Opcional
          'description': 'Cancelamento da compra'
      }
  )

  refund = response.json()

  if refund['success']:
      print(f"Estorno processado: {refund['transaction']['id']}")
      print(f"Valor estornado: R$ {refund['transaction']['refunded_amount'] / 100:.2f}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Estorno Total theme={null}
  {
    "success": true,
    "message": "Estorno PIX processado com sucesso",
    "transaction": {
      "id": 123,
      "payment_id": "860958c4-adf8-438d-8ee6-eff6cf20ed05",
      "status": 6,
      "amount": 10000,
      "refunded_amount": 10000,
      "refunded_at": "2024-01-15T10:30:00Z"
    }
  }
  ```

  ```json 200 - Estorno Parcial theme={null}
  {
    "success": true,
    "message": "Estorno PIX processado com sucesso",
    "transaction": {
      "id": 124,
      "payment_id": "75906707-8c31-479c-b354-aa805c4cefbc",
      "status": 6,
      "amount": 10000,
      "refunded_amount": 5000,
      "refunded_at": "2024-01-15T10:35:00Z"
    }
  }
  ```

  ```json 400 - Transação Não é PIX theme={null}
  {
    "success": false,
    "message": "Esta transação não é do tipo PIX",
    "error": "Use o endpoint /payments/reversal para outros tipos de pagamento"
  }
  ```

  ```json 400 - Transação Não Pode Ser Estornada theme={null}
  {
    "success": false,
    "message": "Transação não pode ser estornada",
    "error": "Transação não está com status PAID"
  }
  ```

  ```json 404 - Transação Não Encontrada theme={null}
  {
    "success": false,
    "message": "Transação não encontrada",
    "error": "Nenhuma transação encontrada com ID: 123"
  }
  ```

  ```json 400 - Prazo Expirado theme={null}
  {
    "success": false,
    "message": "Erro ao processar estorno PIX",
    "error": "Prazo de estorno expirado (90 dias)"
  }
  ```

  ```json 400 - Saldo Insuficiente theme={null}
  {
    "success": false,
    "message": "Erro ao processar estorno PIX",
    "error": "Saldo insuficiente para estorno"
  }
  ```

  ```json 400 - Valor Excede Original theme={null}
  {
    "success": false,
    "message": "Erro ao processar estorno PIX",
    "error": "Valor do estorno excede valor original"
  }
  ```
</ResponseExample>

## Tipos de Estorno

<Tabs>
  <Tab title="Estorno Total">
    ### Estorno Total

    Estorna 100% do valor da transação PIX.

    **Como usar:**

    * Não enviar o campo `amount` no body
    * Ou enviar `amount` igual ao valor original

    **Quando usar:**

    * Cancelamento completo da compra
    * Devolução total do valor pago

    **Exemplo:**

    ```json theme={null}
    {
      "transaction_id": 123,
      "description": "Cancelamento da compra"
    }
    ```
  </Tab>

  <Tab title="Estorno Parcial">
    ### Estorno Parcial

    Estorna apenas parte do valor da transação PIX.

    **Como usar:**

    * Enviar o campo `amount` com o valor desejado em reais
    * Valor deve ser menor que o valor original

    **Quando usar:**

    * Desconto após a compra
    * Devolução parcial de produtos
    * Ajuste de valores

    **Limitações:**

    * Soma de todos os estornos não pode exceder valor original
    * Múltiplos estornos parciais são permitidos

    **Exemplo:**

    ```json theme={null}
    {
      "transaction_id": 124,
      "amount": 50.00,
      "description": "Devolução parcial - 1 item"
    }
    ```
  </Tab>
</Tabs>

## Critérios de Elegibilidade

Para que uma transação PIX possa ser estornada, ela deve atender aos seguintes critérios:

<AccordionGroup>
  <Accordion title="Status da Transação">
    A transação deve estar com status **PAID** (paga). Transações pendentes, canceladas ou já estornadas não podem ser estornadas.
  </Accordion>

  <Accordion title="Prazo de Estorno">
    O estorno deve ser solicitado em até **90 dias** após o pagamento original. Após esse prazo, o estorno não será processado.
  </Accordion>

  <Accordion title="Saldo Disponível">
    A conta deve ter **saldo suficiente** para processar o estorno. O valor será debitado da sua conta e creditado na conta do pagador.
  </Accordion>

  <Accordion title="Valor do Estorno">
    O valor do estorno (ou soma de estornos parciais) não pode exceder o valor original da transação.
  </Accordion>
</AccordionGroup>

## Fluxo do Estorno

<Steps>
  <Step title="Validação">
    Sistema valida se a transação pode ser estornada (status, prazo, saldo)
  </Step>

  <Step title="Processamento">
    Estorno é enviado para a Firebank e processado
  </Step>

  <Step title="Atualização">
    Status da transação é atualizado para REFUNDED (6)
  </Step>

  <Step title="Crédito">
    Valor é creditado na conta do pagador (geralmente instantâneo)
  </Step>
</Steps>

## Códigos de Erro

| Código                          | Descrição                           |
| ------------------------------- | ----------------------------------- |
| `TRANSACTION_NOT_FOUND`         | Transação não encontrada            |
| `TRANSACTION_NOT_PIX`           | Transação não é do tipo PIX         |
| `TRANSACTION_NOT_REFUNDABLE`    | Transação não pode ser estornada    |
| `REFUND_PERIOD_EXPIRED`         | Prazo de estorno expirado (90 dias) |
| `INSUFFICIENT_BALANCE`          | Saldo insuficiente para estorno     |
| `REFUND_VALUE_EXCEEDS_ORIGINAL` | Valor do estorno excede original    |

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Consultar Transação" icon="magnifying-glass" href="/api-reference/transactions/details">
    Verifique se transação é elegível para estorno
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Monitore status dos estornos
  </Card>

  <Card title="Listar Transações" icon="list" href="/api-reference/transactions/list">
    Consulte histórico de estornos
  </Card>

  <Card title="Erros" icon="triangle-exclamation" href="/guides/errors">
    Códigos de erro completos
  </Card>
</CardGroup>