Shop Escrow: Pagamentos Seguros para Donos de Lojas
Quando um jogador compra um produto de uma loja pertencente a um usuário, o pagamento não é mais enviado imediatamente ao dono da loja. Em vez disso, as moedas são mantidas em escrow pelo servidor até que o comprador confirme o recebimento dos bens. Só então o dono da loja recebe seu pagamento — 98% on-chain, com uma 2% de comissão do servidor.
Por que Escrow?
Sem escrow, um dono de loja poderia receber o pagamento e nunca entregar os bens. O comprador não teria nenhum recurso. O escrow protege ambos os lados:
- Compradores podem contestar um pedido se os bens não forem entregues ou não corresponderem à descrição. O pagamento é congelado até que um administrador revise o caso.
- Donos de lojas têm garantia de receber seu pagamento assim que o comprador confirme — ou automaticamente após 7 dias se o comprador não agir.
Como Funciona
1 Comprador paga
O comprador envia o pagamento integral para a Wallet do operador do servidor. As moedas são mantidas em escrow. O status do pedido é definido como escrow.
2 Comprador confirma o recebimento
O comprador chama POST /shop/confirm-receipt para confirmar que recebeu os bens. O servidor envia imediatamente 98% do pagamento para a Wallet do dono da loja on-chain. O servidor mantém uma 2% de comissão.
3 Liberação automática após 7 dias
Se o comprador não confirmar nem contestar dentro de 7 dias, o pagamento é liberado automaticamente ao dono da loja. Um processo em segundo plano verifica a cada hora os escrows expirados.
4 Resolução de disputas
Se o comprador não estiver satisfeito, ele pode chamar POST /shop/dispute para congelar o pagamento. Um administrador então revisa o caso via POST /shop/admin/resolve-payout e:
- Libera o pagamento ao dono da loja, ou
- Reembolsa — o pagamento é cancelado e as moedas permanecem com o servidor (o comprador pode ser compensado manualmente).
Referência de Status de Pagamento
| Status | Meaning |
|---|---|
none | Loja oficial ou sem pedido |
escrow | Moedas mantidas pelo servidor, aguardando confirmação do comprador |
disputed | Comprador contestou, revisão do administrador pendente |
paid | 98% enviado ao dono on-chain |
refunded | Administrador cancelou o pagamento, moedas permanecem com o servidor |
failed | Transferência on-chain falhou |
API Endpoints
| Endpoint | Who | Purpose |
|---|---|---|
POST /shop/confirm-receipt | Comprador | Confirmar recebimento → liberar escrow |
POST /shop/dispute | Comprador | Contestar pedido → congelar escrow |
POST /shop/admin/resolve-payout | Administrador | Resolver disputa (liberar ou reembolsar) |
GET /shop/my-payouts | Dono da loja | Visualizar totais de escrow + pagamentos e histórico |
Seleção de Wallet
O pagamento é enviado para a Wallet do dono da loja na mesma rede do pagamento:
| Payment Currency | Owner Wallet Used |
|---|---|
| CC (Cash Coins) | CC wallet (alternativa: KC wallet) |
| KC (Keshe Coins) | KC wallet |
Divisão de Receita
| Recipient | Share |
|---|---|
| Dono da loja | 98% |
| Comissão do servidor | 2% |
A comissão de 2% cobre os custos de infraestrutura: gás da blockchain (quando aplicável), hospedagem do servidor e o próprio serviço de escrow.
Lojas Oficiais
Lojas oficiais Erleuchtung (pertencentes ao servidor, owner_id IS NULL) são excluÃdas do sistema de escrow. Pagamentos por produtos de lojas oficiais vão diretamente para o servidor sem divisão de pagamento.
O Que Vem a Seguir?
O sistema de escrow já está ativo. Donos de lojas podem acompanhar seus saldos de escrow pendentes e ganhos pagos através do endpoint GET /shop/my-payouts. Um painel frontend para gerenciar pagamentos, confirmar recebimentos e registrar disputas será lançado em uma próxima atualização.