Shop Escrow: Secure Payouts for Shop Owners
When a player buys a product from a user-owned shop, the payment is no longer sent immediately to the shop owner. Instead, the coins are held in escrow by the server until the buyer confirms receipt of the goods. Only then does the shop owner receive their payout — 98% on-chain, with a 2% server commission.
Why Escrow?
Without escrow, a shop owner could receive payment and never deliver the goods. The buyer would have no recourse. Escrow protects both sides:
- Buyers can dispute an order if goods are not delivered or are not as described. The payout is frozen until an admin reviews the case.
- Shop owners are guaranteed to receive their payout once the buyer confirms — or automatically after 7 days if the buyer doesn’t act.
How It Works
1 Buyer pays
The buyer sends the full payment to the server’s operator wallet. The coins are held in escrow. The order status is set to escrow.
2 Buyer confirms receipt
The buyer calls POST /shop/confirm-receipt to confirm they received the goods. The server immediately sends 98% of the payment to the shop owner’s wallet on-chain. The server keeps a 2% commission.
3 Auto-release after 7 days
If the buyer doesn’t confirm or dispute within 7 days, the payout is released automatically to the shop owner. A background worker checks every hour for expired escrows.
4 Dispute resolution
If the buyer is unhappy, they can call POST /shop/dispute to freeze the payout. An admin then reviews the case via POST /shop/admin/resolve-payout and either:
- Releases the payout to the shop owner, or
- Refunds — the payout is cancelled and the coins remain with the server (the buyer can be compensated manually).
Payout Status Reference
| Status | Meaning |
|---|---|
none | Official shop or no order |
escrow | Coins held by server, waiting for buyer confirmation |
disputed | Buyer disputed, admin review pending |
paid | 98% sent to owner on-chain |
refunded | Admin cancelled payout, coins stay with server |
failed | On-chain transfer failed |
API Endpoints
| Endpoint | Who | Purpose |
|---|---|---|
POST /shop/confirm-receipt | Buyer | Confirm receipt → release escrow |
POST /shop/dispute | Buyer | Dispute order → freeze escrow |
POST /shop/admin/resolve-payout | Admin | Resolve dispute (release or refund) |
GET /shop/my-payouts | Shop owner | View escrow + paid totals and history |
Wallet Selection
The payout is sent to the shop owner’s wallet on the same chain as the payment:
| Payment Currency | Owner Wallet Used |
|---|---|
| CC (Cash Coins) | CC wallet (fallback: KC wallet) |
| KC (Keshe Coins) | KC wallet |
Revenue Share
| Recipient | Share |
|---|---|
| Shop owner | 98% |
| Server commission | 2% |
The 2% commission covers infrastructure costs: blockchain gas (where applicable), server hosting, and the escrow service itself.
Official Shops
Official Erleuchtung shops (server-owned, owner_id IS NULL) are excluded from the escrow system. Payments for official shop products go directly to the server with no payout splitting.
What’s Next?
The escrow system is live now. Shop owners can track their pending escrow balances and paid-out earnings via the GET /shop/my-payouts endpoint. A frontend dashboard for managing payouts, confirming receipts, and filing disputes will follow in an upcoming release.