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.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.Cómo funciona
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
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.
Escrow vs Liquidación Directa
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 arriba para saber quién es cada actor.Crear un pago Escrow
Los pagos escrow se crean a través del mismo endpointPOST /payments. No se necesitan pasos adicionales — opcionalmente puedes incluir escrowPayee y/o escrowPlatformFee:
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.
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.
Tanto
escrowPayee como escrowPlatformFee solo aplican para merchants con settlement_mode = escrow. Para merchants con liquidación directa, estos campos se ignoran.Ciclo de vida del pago (Escrow)
Estados específicos de Escrow
Estructura de comisiones
Hay dos tipos de comisiones, deducidas en diferentes etapas:- 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.
- 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.
- 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
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_onlyooperator_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:Próximamente
Endpoint de liberación Escrow
Reembolsos compatibles con Escrow
refund_expired y partial_refund) para pagos en escrow.
Configuración
La liquidación escrow se habilita por merchant. Contacta a [email protected] para configurar:settlement_mode: escrow- Política de liberación para tu caso de uso
- Estructura de comisiones de plataforma
- Despliegue del contrato escrow