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

# Refunds

> Crea refunds en SimplePay usando referencias administradas por SimplePay, con idempotencia, politica de operacion y reconciliacion segura.

Refunds devuelven dinero total o parcialmente. En SimplePay, los refunds deben estar anclados a objetos administrados por SimplePay y a tu razon de negocio.

## Crear refund

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "https://api.simplepay.mx/v1/refunds" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_3001_refund_partial_v1" \
  -d '{
    "payment_intent": "sppi_0123456789abcdef0123456789abcdef",
    "amount": 50000,
    "reason": "requested_by_customer",
    "metadata": {
      "order_id": "order_3001",
      "support_ticket": "SUP-9001"
    }
  }'
```

Campos:

| Campo            | Uso                                                                    |
| ---------------- | ---------------------------------------------------------------------- |
| `payment_intent` | ID SimplePay del pago a reembolsar.                                    |
| `amount`         | Monto parcial en minor units. Omitelo si el flujo permite full refund. |
| `reason`         | `duplicate`, `fraudulent` o `requested_by_customer`.                   |
| `metadata`       | Referencias no secretas para soporte y reconciliacion.                 |

<Danger>
  No construyas refunds publicos con IDs externos no documentados. Usa
  referencias SimplePay y deja que la API aplique tenant scope, policy y
  reconciliacion.
</Danger>

## Listar refunds

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS "https://api.simplepay.mx/v1/refunds?limit=25" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY"
```

## Refunds de Bookable Payments

Para una reserva confirmada, usa el endpoint de booking:

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "https://api.simplepay.mx/v1/bookable-payments/bookings/bkg_123/refund" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bkg_123_refund_v1" \
  -d '{
    "amount_minor": 50000,
    "metadata": {
      "reason": "customer_requested"
    }
  }'
```

Ese flujo actualiza el lifecycle de la reserva y emite eventos Bookable como `booking.refunded` o `booking.partially_refunded`.

## Checklist

<Steps>
  <Step title="Autoriza internamente">
    Tu sistema debe decidir si el agente, merchant o usuario tiene permiso para
    reembolsar.
  </Step>

  <Step title="Usa idempotencia">
    Una pantalla de soporte puede hacer doble click. Tu refund no debe
    duplicarse.
  </Step>

  <Step title="Guarda el resultado">
    Persiste refund ID, amount, payment intent, booking ID si aplica y soporte
    ticket.
  </Step>

  <Step title="Reconcila con webhook">
    Trata el webhook o read API como fuente de verdad para estado final.
  </Step>
</Steps>