Skip to main content

Escrow System

How the escrow payment system works in SigmaOrders.

Overview​

The escrow system is a secure payment method where money is held in a "bank" until items are delivered, protecting both order creators and deliverers.

How It Works​

  1. Order Creation: Payment is deducted and held in escrow (if charge-on-creation enabled)
  2. Delivery: Payment is released to deliverer when items are delivered
  3. Completion: Remaining escrow (if any) is refunded
  4. Cancellation/Expiration: Escrow is refunded automatically

Escrow Balance​

Each order has an escrow_balance that tracks:

  • Money held for the order
  • Payments made to deliverers
  • Remaining balance available

Payment Flow​

On Order Creation​

# If charge-on-creation is enabled
1. Player creates order for $1000
2. $1000 deducted from player balance
3. $1000 added to order escrow_balance
4. Order created with escrow_balance = $1000

On Delivery​

# If pay-on-delivery is enabled
1. Deliverer delivers 32 items (50% of order)
2. $500 released from escrow to deliverer
3. escrow_balance reduced to $500
4. paid_to_deliverers increased to $500

On Completion​

# When all items collected
1. Remaining escrow (if any) refunded
2. Order marked as completed
3. Order auto-deleted

Configuration​

The escrow system is always enabled and cannot be disabled. However, you can configure:

payment:
  charge-on-creation: true   # Charge when order created
  pay-on-delivery: true      # Pay when items delivered

Security Features​

  • Negative Balance Protection: Escrow balance cannot go negative
  • Concurrent Safety: Optimistic locking prevents race conditions
  • Transaction Logging: All escrow operations are logged
  • Automatic Validation: Balance validated on every operation

Refunds​

Escrow is automatically refunded when:

  • Order is cancelled (if auto-refund enabled)
  • Order expires (if auto-refund enabled)
  • Order is completed with remaining balance

Best Practices​

  1. Always Use Escrow: It's the default and most secure
  2. Monitor Escrow: Check for stuck funds periodically
  3. Enable Auto-Refund: Prevents money from being stuck
  4. Review Transaction Logs: Audit escrow operations