# Reembolsos

A API de Reembolsos permite que comerciantes devolvam fundos ao pagador após uma solicitação de pagamento atingir um estado reembolsável. Reembolsos estão no escopo da organização ou conta que possui o ponto de venda da solicitação de pagamento.

## Visão geral

Quando você cria um reembolso, a Fluxis:

1. Valida que suas credenciais de API podem acessar o POS da solicitação de pagamento
2. Verifica se a solicitação está em um status elegível
3. Cria um registro de reembolso em status `processing`
4. Envia um webhook `refund` (se configurado) com o status inicial

::::warning
**A execução on-chain ainda não está implementada.** Registros de reembolso são criados e webhooks são despachados, mas a transferência blockchain que envia fundos para `refund_to_address` ainda está pendente de implementação no serviço de processamento de reembolsos.
::::

## Status elegíveis da solicitação de pagamento

Reembolsos só podem ser criados quando a solicitação de pagamento está em um destes status:

| Status | Uso típico |
| ------ | ----------- |
| `completed` | Pagamento integral recebido; reembolsar o valor pago |
| `overpaid` | Pagador enviou mais que o solicitado |
| `underpaid` | Pagador enviou menos que o solicitado |
| `confirmed` | Transação contábil criada após o pagamento |

Solicitações em `pending`, `created`, `processing`, `expired` ou `failed` **não** são elegíveis.

## Autenticação

Todos os endpoints de reembolso exigem ambos os cabeçalhos:

- `Authorization: Bearer <access_token>`
- `x-fluxis-api-key: <your_api_key>`

Consulte [Autenticação e configuração](/pt/docs/merchant-integration/auth-and-conf) para troca de token.

## Criar um reembolso

```
POST /v1/refunds/payment-request/{paymentRequestID}
```

### Corpo da requisição

| Campo | Obrigatório | Descrição |
| ----- | -------- | ----------- |
| `refund_to_address` | Sim | Endereço blockchain que receberá o reembolso |
| `amount` | Não | String decimal. Se omitido, usa o valor registrado da solicitação de pagamento |
| `reason` | Não | Motivo em texto livre para auditoria |

### Exemplo

```bash
curl -X POST "https://api.fluxis.us/v1/refunds/payment-request/aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-fluxis-api-key: fxs.prd.YOUR_KEY_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "refund_to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "amount": "50.00",
    "reason": "Customer overpaid"
  }'
```

### Resposta (`200`)

```json
{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "refund_to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "amount": "50.00",
    "status": "processing"
  }
}
```

::::note
Quando `amount` é omitido, o reembolso usa o valor armazenado da solicitação de pagamento. Para solicitações `overpaid` ou `underpaid`, esse valor reflete o montante realmente recebido on-chain.
::::

## Obter detalhes do reembolso

```
GET /v1/refunds/{refundID}
```

Retorna metadados completos do reembolso, incluindo rede, ativo, hash da transação de pagamento original e `refund_transaction_hash` após a conclusão do processamento on-chain.

| Campo | Descrição |
| ----- | ----------- |
| `status` | `processing`, `completed` ou `failed` |
| `payment_transaction_hash` | Hash do pagamento recebido original |
| `refund_transaction_hash` | Hash do reembolso de saída (presente após execução on-chain) |
| `unique_asset_id` | Identificador do ativo (ex.: Polygon USDC) |
| `network` | Rede blockchain do reembolso |

Você só pode recuperar reembolsos criados pela mesma entidade autenticada (organização ou conta).

## Status de reembolso

| Status | Significado |
| ------ | ------- |
| `processing` | Registro de reembolso criado; transferência on-chain pendente |
| `completed` | Transação de reembolso confirmada on-chain |
| `failed` | Reembolso não pôde ser concluído |

Hoje, reembolsos recém-criados permanecem em `processing` até que a execução on-chain seja implementada.

## Webhooks

Registre um webhook com `event_type: "refund"` em nível de conta. Na criação, a Fluxis envia:

```json
{
  "data": {
    "notification_type": "refund_status_update",
    "refund_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "payment_request_id": "aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf",
    "status": "processing",
    "amount": "50.00"
  }
}
```

Verifique cada entrega usando [Verificação de assinatura de webhook](/pt/docs/developers/webhook-signature-verification). Consulte [Eventos de webhook](/pt/docs/developers/webhook-events) para o catálogo completo de eventos.

## Erros comuns

| HTTP | Causa |
| ---- | ----- |
| `400` | ID de solicitação inválido, valor ou status de solicitação inelegível |
| `403` | Credenciais de API sem permissão para o POS da solicitação de pagamento |
| `404` | Reembolso não encontrado (apenas GET) |

## Documentação relacionada

- [Solicitações de pagamento](/pt/docs/key-concepts/payment-request) — ciclo de vida e estados extremos
- [Eventos de webhook](/pt/docs/developers/webhook-events) — payload do evento `refund`
- [Transações](/pt/docs/developers/transactions) — registros contábeis após confirmação de pagamento