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

# Pagos

> Cómo funciona el procesamiento de pagos en Ebioro

## Ciclo de vida del pago

Cada pago pasa por una serie de estados:

```mermaid theme={null}
stateDiagram-v2
    [*] --> open: Pago creado
    open --> paid: Cliente envia monto completo
    open --> underpaid: Cliente envia monto parcial
    open --> expired: Timeout de 30 min
    underpaid --> paid: Cliente completa el monto
    underpaid --> underpaid_accepted: Merchant acepta parcial
    paid --> refunded: Merchant emite reembolso
    underpaid_accepted --> refunded: Merchant emite reembolso
```

| Estado               | Descripción                                     |
| -------------------- | ----------------------------------------------- |
| `open`               | Pago creado, esperando al cliente               |
| `paid`               | Monto completo recibido, liquidación en proceso |
| `underpaid`          | Monto parcial recibido, esperando complemento   |
| `underpaid_accepted` | Merchant aceptó pago parcial                    |
| `expired`            | Pago expiró (30 minutos)                        |
| `refunded`           | Pago fue reembolsado                            |

## Liquidación

Cuando un pago se marca como `paid`, el proceso de liquidación comienza automáticamente:

1. Se deduce la comisión de la plataforma
2. Se calcula la comisión del partner (si aplica)
3. El monto neto se transfiere a la cuenta de recepción del merchant
4. Se envía webhook con `settlement_status: "paid"`

La liquidación es en **USDC** en la red Stellar.

## Montos

Todos los montos en la API están en la **unidad más pequeña** de la moneda:

* `1000` USD = \$10.00
* `settlement_amount` de `1000` = 10.00 USDC

## Crear un pago

<Note>
  El `amount.value` está en la unidad más pequeña de la moneda. Para USD, esto significa centavos.
  Entonces `1000` = \$10.00.
</Note>

```json theme={null}
{
  "amount": {
    "value": 1000,
    "currency": "USD"
  },
  "description": "Orden #1234",
  "redirectUrl": "https://tusitio.com/exito",
  "webhookUrl": "https://tusitio.com/webhook"
}
```

La API devuelve un `checkout_id` y un `qrCode` (URI SEP-7) que el cliente puede escanear con cualquier wallet de Stellar.

## Idempotencia

Los reintentos de red y los envíos duplicados pueden crear pagos duplicados. Para que `POST /payments` sea seguro de reintentar, envía un encabezado **`Idempotency-Key`** — una cadena única (máximo 255 caracteres) que identifica la solicitud lógica:

```bash theme={null}
POST /payments
Idempotency-Key: order-1234
```

* Si una solicitud con la misma clave se reenvía después de que la primera se completó, se devuelve la **respuesta del pago original** — no se crea un segundo pago.
* Si la solicitud original aún se está procesando, el reintento recibe **409**. El 409 siempre es transitorio — usa un retroceso exponencial corto (p. ej. reintenta tras 1s, luego 2s).
* Reutilizar una clave con un **cuerpo de solicitud distinto** devuelve **422** (indica un error del cliente).
* Una clave de más de 255 caracteres devuelve **400**.

Usa una clave estable para un mismo pedido lógico — por ejemplo el id de tu pedido (`order-1234`). Los plugins oficiales de e-commerce (WooCommerce, PrestaShop, Odoo) lo hacen automáticamente, usando el pedido como clave.

Si omites el encabezado, cada solicitud crea un nuevo pago.