Escrow de Tienda: Pagos seguros para propietarios de tiendas
Cuando un jugador compra un producto en una tienda propiedad de un usuario, el pago ya no se envía inmediatamente al propietario de la tienda. En su lugar, los coins se retienen en escrow por el servidor hasta que el comprador confirme la recepción de la mercancía. Solo entonces el propietario de la tienda recibe su pago — 98% on-chain, con una comisión del 2% para el servidor.
¿Por qué Escrow?
Sin escrow, un propietario de tienda podría recibir el pago y nunca entregar la mercancía. El comprador no tendría ningún recurso. El escrow protege a ambas partes:
- Los compradores pueden disputar un pedido si la mercancía no se entrega o no corresponde a la descripción. El pago se congela hasta que un administrador revise el caso.
- Los propietarios de tiendas tienen la garantía de recibir su pago una vez que el comprador confirma — o automáticamente después de 7 días si el comprador no actúa.
Cómo funciona
1 El comprador paga
El comprador envía el pago completo a la Wallet operadora del servidor. Los coins se retienen en escrow. El estado del pedido se establece en escrow.
2 El comprador confirma la recepción
El comprador llama a POST /shop/confirm-receipt para confirmar que recibió la mercancía. El servidor envía inmediatamente el 98% del pago on-chain a la Wallet del propietario de la tienda. El servidor retiene una comisión del 2%.
3 Liberación automática después de 7 días
Si el comprador no confirma ni disputa dentro de 7 días, el pago se libera automáticamente al propietario de la tienda. Un proceso en segundo plano verifica cada hora los escrows expirados.
4 Resolución de disputas
Si el comprador no está satisfecho, puede llamar a POST /shop/dispute para congelar el pago. Un administrador luego revisa el caso a través de POST /shop/admin/resolve-payout y ya sea:
- Libera el pago al propietario de la tienda, o
- Reembolsa — el pago se cancela y los coins permanecen con el servidor (el comprador puede ser compensado manualmente).
Referencia de estados de pago
| Estado | Significado |
|---|---|
none | Tienda oficial o sin pedido |
escrow | Coins retenidos por el servidor, esperando confirmación del comprador |
disputed | El comprador disputó, revisión del administrador pendiente |
paid | 98% enviado al propietario on-chain |
refunded | El administrador canceló el pago, los coins permanecen con el servidor |
failed | La transferencia on-chain falló |
Endpoints de API
| Endpoint | Quién | Propósito |
|---|---|---|
POST /shop/confirm-receipt | Comprador | Confirmar recepción → liberar escrow |
POST /shop/dispute | Comprador | Disputar pedido → congelar escrow |
POST /shop/admin/resolve-payout | Administrador | Resolver disputa (liberar o reembolsar) |
GET /shop/my-payouts | Propietario de tienda | Ver totales de escrow + pagados e historial |
Selección de Wallet
El pago se envía a la Wallet del propietario de la tienda en la misma cadena que el pago:
| Moneda de pago | Wallet del propietario utilizada |
|---|---|
| CC (Cash Coins) | CC wallet (alternativa: KC wallet) |
| KC (Keshe Coins) | KC wallet |
Distribución de ingresos
| Beneficiario | Participación |
|---|---|
| Propietario de la tienda | 98% |
| Comisión del servidor | 2% |
La comisión del 2% cubre los costos de infraestructura: gas de blockchain (cuando corresponda), alojamiento del servidor y el propio servicio de escrow.
Tiendas oficiales
Las tiendas oficiales de Erleuchtung (propiedad del servidor, owner_id IS NULL) están excluidas del sistema de escrow. Los pagos por productos de tiendas oficiales van directamente al servidor sin división de pago.
¿Qué sigue?
El sistema de escrow ya está en funcionamiento. Los propietarios de tiendas pueden rastrear sus saldos de escrow pendientes y sus ganancias pagadas a través del endpoint GET /shop/my-payouts. Un panel frontend para gestionar pagos, confirmar recepciones y presentar disputas seguirá en una próxima versión.