> ## 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 Escrow

> Retén fondos en un contrato inteligente hasta que se cumplan las condiciones antes de liberar al merchant o beneficiario

## Descripción general

Los pagos escrow permiten que los fondos se **bloqueen en un contrato inteligente Soroban** en la red Stellar hasta que se cumplan condiciones predefinidas. En lugar de liquidar directamente a la cuenta del merchant, los fondos se retienen en escrow y se liberan según una **política de liberación** configurable.

Esto es útil para escenarios donde la confianza entre las partes necesita ser aplicada programáticamente — marketplaces, entrega de servicios, remesas e integraciones punto de venta.

<Note>
  El escrow se configura a nivel de **merchant**. Cuando el `settlement_mode` de un merchant está configurado como `escrow`, todos los pagos de ese merchant fluyen a través del contrato escrow automáticamente.
</Note>

## Cómo funciona

```mermaid theme={null}
sequenceDiagram
    participant M as Merchant / Plataforma
    participant E as Ebioro API
    participant SC as Contrato Escrow
    participant C as Cliente

    M->>E: 1. Crear pago (con escrowPayee)
    E-->>M: Pago creado (checkout_id)
    C->>E: 2. Cliente paga (Stellar o cross-chain)
    E->>SC: 3. Crear orden escrow + fondear
    SC->>SC: 4. Fondos bloqueados en contrato
    E->>M: 5. Webhook: pago confirmado (escrow_status: funded)
    Note over M,SC: Entrega del servicio / envío de productos
    M->>E: 6. Solicitud de liberación
    E->>SC: 7. Contrato libera fondos
    SC->>SC: 8. Comisiones deducidas, beneficiario recibe neto
    E->>M: 9. Webhook: liquidación completa
```

## Roles

Cada pago escrow involucra hasta cuatro roles. Entender quién es quién es esencial para elegir la configuración correcta.

### Pagador (Cliente / Remitente)

La persona o entidad que **envía el dinero**. Es el cliente que compra un producto, el pasajero que paga un viaje, o el remitente en una transferencia internacional. Los fondos del pagador se bloquean en el contrato escrow hasta que se cumplan las condiciones de liberación.

**Ejemplos:** un cliente en una tienda online, un pasajero en una app de transporte, un remitente enviando dinero al exterior.

### Beneficiario (Receptor / Proveedor de servicio)

La persona o entidad que **recibe el dinero** una vez que los fondos son liberados. Es quien entrega el producto, presta el servicio, o paga la remesa localmente.

**Ejemplos:** un conductor (Uber), un anfitrión (Airbnb), un freelancer (Upwork), un operador de remesas licenciado, un comerciante en una tienda física.

### Dueño de la plataforma

La entidad que **posee la instancia escrow** y puede tener la autoridad para liberar o reembolsar pagos dependiendo de la política de liberación. El dueño de la plataforma se establece cuando se despliega el contrato escrow.

* En un **marketplace**, el dueño de la plataforma es la empresa del marketplace (ej. la empresa de transporte o la plataforma de freelancers).
* En un **flujo de remesas**, el dueño de la plataforma es típicamente Ebioro.
* En una **integración POS**, el dueño de la plataforma puede ser el proveedor de TI o Ebioro.

### Operador Ebioro

La dirección del sistema de Ebioro, que actúa como la **capa de infraestructura de pagos**. En ciertas políticas de liberación (`operator_or_payee`, `operator_after_timeout`), el operador Ebioro tiene la autoridad para liberar fondos del contrato escrow.

### Referencia rápida

| Rol                        | ¿Quién es?                | Ejemplos del mundo real                                            |
| -------------------------- | ------------------------- | ------------------------------------------------------------------ |
| **Pagador**                | El que paga               | Cliente, pasajero, remitente                                       |
| **Beneficiario**           | El que recibe el pago     | Conductor, anfitrión, freelancer, comerciante, operador de remesas |
| **Dueño de la plataforma** | El que controla el escrow | Empresa del marketplace, Ebioro, proveedor de TI                   |
| **Operador Ebioro**        | Infraestructura de pagos  | Ebioro (siempre)                                                   |

<Note>
  El **beneficiario** y el **dueño de la plataforma** pueden ser la misma entidad. Por ejemplo, en un flujo de remesas el operador licenciado es tanto el beneficiario (recibe los fondos) como el merchant. En un marketplace, el conductor es el beneficiario pero la empresa del marketplace es el dueño de la plataforma.
</Note>

***

## Escrow vs Liquidación Directa

| Característica         | Liquidación Directa                | Liquidación Escrow                 |
| ---------------------- | ---------------------------------- | ---------------------------------- |
| Destino de fondos      | Wallet del merchant inmediatamente | Bloqueados en contrato inteligente |
| Control de liberación  | Automático al pago                 | Según política de liberación       |
| Reembolsos             | Pago Stellar directo               | Reembolso basado en contrato       |
| Comisión Ebioro        | En liquidación                     | Antes del escrow                   |
| Comisión de plataforma | En liquidación                     | En liberación                      |
| Ideal para             | Pagos simples                      | Marketplaces, servicios, remesas   |

## Políticas de liberación

Cada merchant escrow se configura con una política de liberación que determina **quién puede liberar los fondos** y **cuándo**. Consulta [Roles](#roles) arriba para saber quién es cada actor.

| Política                 | Quién puede liberar                       | Cuándo                                     | Ideal para                                 |
| ------------------------ | ----------------------------------------- | ------------------------------------------ | ------------------------------------------ |
| `platform_only`          | Solo el **dueño de la plataforma**        | En cualquier momento antes del vencimiento | Marketplaces, remesas                      |
| `payee_only`             | Solo el **beneficiario**                  | En cualquier momento antes del vencimiento | Vendedores de confianza                    |
| `operator_or_payee`      | **Operador Ebioro** o el **beneficiario** | En cualquier momento antes del vencimiento | POS / pagos a merchants                    |
| `payer_confirmation`     | Solo el **pagador**                       | En cualquier momento antes del vencimiento | Transacciones protegidas para el comprador |
| `operator_after_timeout` | Solo el **operador Ebioro**               | Después del período de espera              | Off-ramp de efectivo con ventana de espera |

## Crear un pago Escrow

Los pagos escrow se crean a través del mismo endpoint `POST /payments`. No se necesitan pasos adicionales — opcionalmente puedes incluir `escrowPayee` y/o `escrowPlatformFee`:

```json theme={null}
{
  "amount": {
    "value": 5000,
    "currency": "USD"
  },
  "description": "Viaje #4521",
  "redirectUrl": "https://tusitio.com/exito",
  "webhookUrl": "https://tusitio.com/webhook",
  "escrowPayee": "GBXYZ...DIRECCION_STELLAR_BENEFICIARIO",
  "escrowPlatformFee": 500
}
```

| Campo               | Requerido | Descripción                                                                                                                                                            |
| ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `escrowPayee`       | Opcional  | Dirección Stellar del receptor de los fondos. Si se omite, **se usa la cuenta Stellar del merchant por defecto**.                                                      |
| `escrowPlatformFee` | Opcional  | Comisión de plataforma en puntos base (1% = 100 bps) deducida al momento de la liberación. Si se omite, **se usa la comisión de plataforma configurada del merchant**. |

Cuándo usar `escrowPayee`:

* **Transporte / entregas (Uber)**: Usa la dirección del conductor o mensajero — cambia por orden.
* **Plataformas de alquiler (Airbnb)**: Usa la dirección del anfitrión o propietario.
* **Freelance / marketplaces de servicios (Upwork)**: Usa la dirección del freelancer o proveedor de servicios.
* **Remesas / POS**: No lo envíes — el merchant es el beneficiario, así que el valor por defecto es correcto.

Cuándo usar `escrowPlatformFee`:

* Cuando la comisión de plataforma varía por orden (ej. diferentes tasas de comisión por tipo de servicio o cliente).
* Si no se envía, se usa la comisión de plataforma por defecto del merchant.

<Note>
  Tanto `escrowPayee` como `escrowPlatformFee` solo aplican para merchants con `settlement_mode = escrow`. Para merchants con liquidación directa, estos campos se ignoran.
</Note>

## Ciclo de vida del pago (Escrow)

```mermaid theme={null}
stateDiagram-v2
    [*] --> open: Pago creado
    open --> paid: Cliente envía monto completo
    open --> expired: Timeout de 30 min
    paid --> escrow_funded: Fondos bloqueados en contrato
    escrow_funded --> released: Condiciones de liberación cumplidas
    escrow_funded --> refunded: Reembolso total (expirado o vía contrato)
    escrow_funded --> partially_refunded: Reembolso parcial
    partially_refunded --> released: Monto restante liberado al beneficiario
    partially_refunded --> partially_refunded: Reembolso parcial adicional
```

### Estados específicos de Escrow

| Estado               | Descripción                                                       |
| -------------------- | ----------------------------------------------------------------- |
| `escrow_funded`      | Fondos bloqueados en el contrato escrow                           |
| `partially_refunded` | Parte del monto en escrow ha sido reembolsada al pagador          |
| `released`           | Fondos restantes liberados al beneficiario (comisiones deducidas) |
| `refunded`           | Monto total reembolsado al pagador                                |

## Estructura de comisiones

Hay dos tipos de comisiones, deducidas en diferentes etapas:

1. **Comisión de procesamiento Ebioro** — deducida **antes** de que los fondos entren al contrato escrow. El monto bloqueado en escrow ya es neto de esta comisión. Las comisiones de procesamiento escrow son diferentes a las de liquidación directa.

2. **Comisión de plataforma** — deducida **al momento de la liberación** del monto en escrow. Es la comisión del marketplace o partner, configurada por merchant.

**Ejemplo:**

* Cliente paga: \$100 USDC
* Comisión de procesamiento Ebioro: deducida antes del escrow
* Monto bloqueado en escrow: neto de la comisión Ebioro
* Comisión de plataforma: deducida al liberar
* **Beneficiario recibe: monto neto después de ambas comisiones**

Contacta a [support@ebioro.com](mailto:support@ebioro.com) para tarifas específicas.

## Casos de uso

### Marketplace / Economía Gig

Una plataforma de transporte o entregas donde los clientes pagan por adelantado y los conductores reciben el pago después de completar el servicio.

* **Política de liberación:** `platform_only`
* **Flujo:** Cliente paga → fondos bloqueados → servicio entregado → plataforma confirma → conductor recibe pago

### POS / E-commerce

Un proveedor de TI integra Ebioro como método de pago para tiendas físicas o tiendas en línea.

* **Política de liberación:** `platform_only` o `operator_or_payee`
* **Flujo:** Cliente paga en checkout → fondos bloqueados → merchant confirma entrega → fondos liberados

### Entrega de remesas vía operador licenciado

Un remitente inicia un pago transfronterizo. Un operador local licenciado entrega los fondos (depósito bancario, pago en efectivo) al destinatario. Ebioro valida la entrega antes de liberar los fondos.

* **Política de liberación:** `platform_only`
* **Flujo:** Remitente paga → fondos bloqueados → operador entrega localmente → Ebioro valida entrega → operador recibe pago

### Off-ramp de efectivo

Un operador de efectivo licenciado permite a los usuarios convertir crypto a efectivo físico en una ubicación física.

* **Política de liberación:** `operator_after_timeout`
* **Flujo:** Usuario paga → fondos bloqueados → efectivo entregado → ventana de espera → operador libera después del timeout

## Webhooks

Los pagos escrow envían los mismos eventos webhook que los pagos regulares, con campos adicionales de escrow:

```json theme={null}
{
  "event": "payment.updated",
  "data": {
    "checkout_id": "chk_abc123",
    "status": "paid",
    "escrow_status": "funded",
    "escrow_order_id": "42",
    "escrow_contract_address": "CXYZ...CONTRATO"
  }
}
```

## Próximamente

<Warning>
  Las siguientes funcionalidades están planificadas pero aún no están disponibles en la API.
</Warning>

### Endpoint de liberación Escrow

```
POST /payments/:id/release
```

Activa la liberación de fondos en escrow al beneficiario. Solo disponible para merchants o plataformas autorizadas según la política de liberación.

### Reembolsos compatibles con Escrow

```
POST /payments/:id/refunds
```

Actualmente, los reembolsos para pagos escrow no están soportados. Una actualización futura integrará reembolsos basados en contrato (`refund_expired` y `partial_refund`) para pagos en escrow.

## Configuración

La liquidación escrow se habilita por merchant. Contacta a [support@ebioro.com](mailto:support@ebioro.com) para configurar:

* `settlement_mode: escrow`
* Política de liberación para tu caso de uso
* Estructura de comisiones de plataforma
* Despliegue del contrato escrow