Skip to main content

Economy Configuration

Configure payment methods, escrow, and refund settings.

Payment Method​

economy:
  payment-method: ESCROW  # ESCROW or IMMEDIATE
  require-payment-confirmation: false

payment-method​

Type: String
Options: ESCROW, IMMEDIATE
Default: ESCROW
Description: Payment processing method

ESCROW (Recommended):

  • Payment held in secure "bank" until delivery
  • Guarantees payment for deliverers
  • Protects order creators
  • Default and recommended method

IMMEDIATE:

  • Payment made when items are collected
  • Less secure (no guarantee for deliverers)
  • Not recommended for most servers

Payment System​

payment:
  # Payment timing
  charge-on-creation: true   # Charge when order is created
  pay-on-delivery: true      # Pay deliverer when items delivered
  
  # Refund settings
  refund:
    enabled: true
    deduction-percentage: 0.0  # 0.0 to 1.0 (0% to 100%)
    deduction-fixed: 0.0       # Fixed amount
    use-percentage: true        # true = percentage, false = fixed
    auto-refund-on-expiration: true
    auto-refund-on-cancel: true
  
  # Cancellation settings
  cancellation:
    allow-cancel-with-deliveries: false
    require-admin-approval: false
    min-time-before-cancel: 0  # seconds

Charge Settings​

charge-on-creation​

Type: Boolean
Default: true
Description: Charge player when order is created

Behavior:

  • If true: Payment deducted immediately, held in escrow
  • If false: No payment on creation (not recommended)
  • Escrow system always enabled regardless of this setting

pay-on-delivery​

Type: Boolean
Default: true
Description: Pay deliverer when items are delivered

Behavior:

  • If true: Deliverer paid immediately upon delivery
  • Payment is proportional to items delivered
  • If false: Deliverer not paid (not recommended)

Refund Configuration​

Refund Deduction​

Refunds can have fees deducted:

Percentage Deduction:

refund:
  deduction-percentage: 0.05  # 5% fee
  use-percentage: true

Fixed Deduction:

refund:
  deduction-fixed: 10.0  # $10 fee
  use-percentage: false

Auto-Refund Settings​

auto-refund-on-expiration:

  • Automatically refund expired orders
  • Refund amount = escrow balance
  • Deduction fees apply if configured

auto-refund-on-cancel:

  • Automatically refund when order is cancelled
  • Refund amount = escrow balance
  • Deduction fees apply if configured

Cancellation Settings​

allow-cancel-with-deliveries​

Type: Boolean
Default: false
Description: Allow cancelling orders that have deliveries

Behavior:

  • If false: Orders with deliveries can't be cancelled
  • If true: Orders can be cancelled even with partial deliveries
  • Admin can always cancel regardless

require-admin-approval​

Type: Boolean
Default: false
Description: Require admin approval for cancellation with deliveries

Note: Currently not fully implemented, cancellation is blocked if deliveries exist.

min-time-before-cancel​

Type: Integer (seconds)
Default: 0
Description: Minimum time before order can be cancelled

Example:

min-time-before-cancel: 300  # 5 minutes

Escrow System​

The escrow system is always enabled and cannot be disabled. It ensures:

  • Order creators can't lose money without receiving items
  • Deliverers are guaranteed payment
  • Secure transaction handling

How Escrow Works​

  1. Order Creation: Payment held in escrow (if charge-on-creation enabled)
  2. Delivery: Payment released to deliverer (if pay-on-delivery enabled)
  3. Completion: Remaining escrow refunded (if any)
  4. Expiration/Cancellation: Escrow refunded automatically

Configuration Examples​

No-Refund-Fee Setup​

economy:
  payment-method: ESCROW

payment:
  charge-on-creation: true
  pay-on-delivery: true
  refund:
    enabled: true
    deduction-percentage: 0.0
    deduction-fixed: 0.0
    use-percentage: true
    auto-refund-on-expiration: true
    auto-refund-on-cancel: true

Refund-Fee Setup​

economy:
  payment-method: ESCROW

payment:
  charge-on-creation: true
  pay-on-delivery: true
  refund:
    enabled: true
    deduction-percentage: 0.10  # 10% fee
    use-percentage: true
    auto-refund-on-expiration: true
    auto-refund-on-cancel: true

Strict Cancellation​

payment:
  cancellation:
    allow-cancel-with-deliveries: false
    require-admin-approval: true
    min-time-before-cancel: 600  # 10 minutes

Best Practices​

  1. Always Use ESCROW: Most secure payment method
  2. Enable Auto-Refunds: Prevents stuck money
  3. Set Reasonable Fees: Balance between server economy and player experience
  4. Test Payment Flow: Verify payments work correctly
  5. Monitor Escrow: Check for stuck funds periodically

Troubleshooting​

Payments Not Working​

Check:

  1. Vault is installed and working
  2. Economy plugin is connected to Vault
  3. Players have sufficient balance
  4. Payment settings are correct

Refunds Not Processing​

Check:

  1. Auto-refund settings are enabled
  2. Escrow balance exists
  3. Economy plugin is working
  4. Check transaction logs

Next Steps​