# Reembolsos

La API de Reembolsos permite a los comercios devolver fondos a un pagador después de que una solicitud de pago alcance un estado reembolsable. Los reembolsos están limitados a la organización o cuenta que posee el punto de venta de la solicitud de pago.

## Resumen

Cuando creas un reembolso, Fluxis:

1. Valida que tus credenciales API puedan acceder al POS de la solicitud de pago
2. Comprueba que la solicitud de pago esté en un estado elegible
3. Crea un registro de reembolso en estado `processing`
4. Envía un webhook `refund` (si está configurado) con el estado inicial

::::warning
**La ejecución on-chain aún no está implementada.** Se crean registros de reembolso y se despachan webhooks, pero la transferencia blockchain que envía fondos a `refund_to_address` aún está pendiente de implementación en el servicio de procesamiento de reembolsos.
::::

## Estados elegibles de solicitud de pago

Los reembolsos solo pueden crearse cuando la solicitud de pago está en uno de estos estados:

| Estado | Uso típico |
| ------ | ----------- |
| `completed` | Pago completo recibido; reembolsar el monto pagado |
| `overpaid` | El pagador envió más de lo solicitado |
| `underpaid` | El pagador envió menos de lo solicitado |
| `confirmed` | Transacción de libro creada después del pago |

Las solicitudes en `pending`, `created`, `processing`, `expired` o `failed` **no** son elegibles.

## Autenticación

Todos los endpoints de reembolso requieren ambos encabezados:

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

Consulta [Autenticación y configuración](/es/docs/merchant-integration/auth-and-conf) para el intercambio de tokens.

## Crear un reembolso

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

### Cuerpo de la solicitud

| Campo | Requerido | Descripción |
| ----- | -------- | ----------- |
| `refund_to_address` | Sí | Dirección blockchain que recibirá el reembolso |
| `amount` | No | Cadena decimal. Si se omite, usa el monto registrado de la solicitud de pago |
| `reason` | No | Motivo en texto libre para auditoría |

### Ejemplo

```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"
  }'
```

### Respuesta (`200`)

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

::::note
Cuando se omite `amount`, el reembolso usa el monto almacenado de la solicitud de pago. Para solicitudes `overpaid` o `underpaid`, ese valor refleja el monto realmente recibido on-chain.
::::

## Obtener detalles del reembolso

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

Devuelve metadatos completos del reembolso incluyendo red, activo, hash de la transacción de pago original y `refund_transaction_hash` una vez que se complete el procesamiento on-chain.

| Campo | Descripción |
| ----- | ----------- |
| `status` | `processing`, `completed` o `failed` |
| `payment_transaction_hash` | Hash del pago entrante original |
| `refund_transaction_hash` | Hash del reembolso saliente (presente tras ejecución on-chain) |
| `unique_asset_id` | Identificador de activo (p. ej. Polygon USDC) |
| `network` | Red blockchain del reembolso |

Solo puedes recuperar reembolsos creados por la misma entidad autenticada (organización o cuenta).

## Estados de reembolso

| Estado | Significado |
| ------ | ------- |
| `processing` | Registro de reembolso creado; transferencia on-chain pendiente |
| `completed` | Transacción de reembolso confirmada on-chain |
| `failed` | El reembolso no pudo completarse |

Hoy, los reembolsos recién creados permanecen en `processing` hasta que se implemente la ejecución on-chain.

## Webhooks

Registra un webhook con `event_type: "refund"` a nivel de cuenta. Al crear, Fluxis envía:

```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"
  }
}
```

Verifica cada entrega usando [Verificación de firma de webhook](/es/docs/developers/webhook-signature-verification). Consulta [Eventos de webhook](/es/docs/developers/webhook-events) para el catálogo completo de eventos.

## Errores comunes

| HTTP | Causa |
| ---- | ----- |
| `400` | ID de solicitud de pago inválido, monto o estado de solicitud no elegible |
| `403` | Las credenciales API carecen de permiso para el POS de la solicitud de pago |
| `404` | Reembolso no encontrado (solo GET) |

## Documentación relacionada

- [Solicitudes de pago](/es/docs/key-concepts/payment-request) — ciclo de vida y estados límite
- [Eventos de webhook](/es/docs/developers/webhook-events) — payload del evento `refund`
- [Transacciones](/es/docs/developers/transactions) — registros de libro tras confirmación de pago