Skip to content

User Wallets

Purpose

Manage customer digital wallet balances for store credit and advance payments. Track wallet funds that customers can use for purchases or receive as refunds.

Accessing User Wallets

Navigate to: Delivery & Payments > User Wallets from the sidebar

List View

User Wallets List

The list displays customer wallets with their current balances and activity status.

Table Columns

User Name

  • Format: Text
  • Purpose: Customer name associated with this wallet

User Email

  • Format: Email address
  • Purpose: Customer email address (hidden by default)

Balance

  • Format: Money value (color-coded green if positive)
  • Purpose: Current wallet balance in customer's currency

Currency

  • Format: Badge (3-letter code)
  • Purpose: Currency used for this wallet (USD, EUR, etc.)

Active Status

  • Format: Icon badge (checkmark = active, X = inactive)
  • Purpose: Whether the wallet is currently active for transactions

Transaction Count

  • Format: Badge with number
  • Purpose: Total number of transactions in this wallet

Row Actions

  • Edit: Modify wallet settings
  • Add Funds: Credit money to the wallet
  • Deduct Funds: Withdraw money from wallet
  • View Transactions: See wallet transaction history

Bulk Actions

  • Delete: Remove multiple wallets
  • Export: Export wallet data to Excel/CSV

Viewing a Wallet

Click any wallet row to view detailed information and manage the wallet.

Creating a User Wallet

Create User Wallet

While wallets are typically created automatically for customers, you can create one manually if needed.

Form Fields

User Required

  • Type: Searchable dropdown with inline create
  • Purpose: Select the customer for this wallet
  • Options: All registered customers

Balance Required

  • Type: Currency input (2 decimal places, prefix: $)
  • Default: 0.00
  • Purpose: Initial wallet balance
  • Step: 0.01

Currency Required

  • Type: Text input (max 3 characters, default: USD)
  • Purpose: Currency code for wallet transactions
  • Examples: USD, EUR, GBP, AED

Is Active Required

  • Type: Toggle switch (On/Off)
  • Default: On (enabled)
  • Purpose: Enable/disable wallet for transactions

Managing Wallet Funds

Adding Funds

Click the Add Funds button to credit money to a customer's wallet.

Form:

  • Amount: Decimal amount to add
  • Description: Reason for credit (e.g., "Refund", "Promotional credit", "Manual adjustment")

After adding:

  • Balance is updated immediately
  • Transaction record is created automatically
  • Customer receives notification (if enabled)

Deducting Funds

Click the Deduct Funds button to withdraw from a customer's wallet.

Form:

  • Amount: Decimal amount to deduct
  • Description: Reason for debit (e.g., "Correction", "Chargeback", "Manual adjustment")

Validation:

  • Cannot deduct more than current balance
  • System shows error if insufficient funds

Viewing Transactions

Click View Transactions to see all wallet activity including:

  • Credits (purchases reversed, promotions, refunds)
  • Debits (store purchases, manual adjustments)
  • Balance before/after each transaction
  • Transaction dates and descriptions

Editing a Wallet

Click Edit to change wallet settings:

  • Balance (though Add/Deduct Funds is recommended for tracking)
  • Active status
  • Currency

Wallet Filters

Use filters to find specific wallets:

  • Active Status: Show only active or inactive wallets
  • Currency: Filter by wallet currency
  • Has Balance: Show wallets with positive balance

Key Information

  • Per-Customer: Each customer has one wallet per currency
  • Balance Tracking: All changes recorded in transaction history
  • Automatic Creation: Wallets created automatically when customers join
  • Multi-Currency: Support for different currencies per customer
  • Transaction History: Every fund change creates a permanent record
  • Activation: Inactive wallets cannot be used for purchases
  • Store Credit: Wallet balances can be used as payment during checkout

Multi-Currency Wallets

Multi-Currency Wallets

Multi-Currency Wallets is a premium feature that allows customers to maintain separate wallet balances for different currencies. This is particularly useful for international businesses or stores that accept multiple currencies.

Overview

Standard Wallet System (default): - Each customer has one wallet with a single balance - All transactions use the store's base currency - Simple and straightforward for single-currency stores

Multi-Currency Wallet System (premium): - Each customer can have multiple wallets, one per currency - Separate balance for USD, EUR, SAR, GBP, etc. - Currency-specific deposits, withdrawals, and transactions - More flexibility for international customers

Enabling Multi-Currency Wallets

To enable multi-currency wallet support:

  1. Navigate to System Settings → Advanced Tab
  2. Scroll to Wallet Settings section
  3. Toggle "Enable Multi-Currency Wallets" to ON
  4. Click Save changes

Important: - This feature is only available for paid store plans - Free stores will see an upgrade prompt when attempting to enable - See System Settings - Multi-Currency Wallets for configuration details

How Multi-Currency Wallets Work

When multi-currency is enabled:

Customer Perspective

  1. Multiple Balances: Customer can have USD wallet, EUR wallet, SAR wallet, etc.
  2. Currency Selection: When depositing or withdrawing, customer chooses which currency
  3. Automatic Matching: System uses the wallet that matches the order currency for payments
  4. Separate History: Each currency wallet has its own transaction history

Admin Perspective

  1. Multiple Wallet Records: Each customer may have multiple wallet rows (one per currency)
  2. Currency Column: Easily identify which currency each wallet uses
  3. Individual Management: Add/deduct funds to specific currency wallets
  4. Consolidated View: All customer wallets visible in one list

Managing Multi-Currency Wallets

Creating Currency-Specific Wallets

When creating a new wallet for a customer with multi-currency enabled:

  1. Click Create button
  2. Select the customer
  3. Currency field: Enter the 3-letter currency code (USD, EUR, SAR, etc.)
  4. Set initial balance
  5. Toggle Is Active to ON
  6. Click Create

Example: Creating EUR wallet for a customer who already has a USD wallet

  • User: John Doe
  • Balance: 0.00
  • Currency: EUR
  • Is Active: Yes

Result: John now has two wallets (USD and EUR) and can maintain separate balances.

Adding Funds to Specific Currency

When using Add Funds action:

  1. Select the wallet with the desired currency
  2. Click Add Funds
  3. Enter amount (will be added in that wallet's currency)
  4. Enter description
  5. Confirm

Example: If you click "Add Funds" on John's EUR wallet and enter 100, it adds €100 to his EUR balance (not his USD balance).

Currency Selection for Transactions

Deposits/Withdrawals/Transfers: - Customer selects which currency wallet to use - See Wallet Deposit Requests - See Wallet Withdrawal Requests - See Wallet Transfers

Payments: - System automatically uses the wallet matching the order currency - Example: EUR order → EUR wallet is used - If customer doesn't have a wallet in the order currency, payment fails

Best Practices for Multi-Currency Wallets

When to Enable

Enable multi-currency wallets if: - You sell in multiple currencies - You have international customers - You accept payments in various currencies - You want customers to maintain balances in their preferred currency

Keep single currency if: - You only operate in one currency - All customers use the same currency - You want simpler wallet management - You're on a free plan (feature not available)

Managing Exchange Rates

Important: The wallet system does NOT automatically convert between currencies.

  • Each currency wallet is independent
  • €100 in EUR wallet stays €100 (doesn't convert to USD)
  • Customers cannot transfer between their own currency wallets
  • If you need to convert, manually:
  • Deduct from one currency wallet
  • Calculate exchange rate
  • Add equivalent to other currency wallet

Communication

Make sure customers understand: - They can have multiple currency wallets - Each wallet balance is separate (no auto-conversion) - They should deposit in the currency they plan to use - Refunds are returned in the original transaction currency

Troubleshooting Multi-Currency

Payment Fails Due to Currency Mismatch

Problem: Customer tries to pay for EUR order but only has USD wallet

Solution: - Customer needs to deposit funds to EUR wallet first - Or customer can pay with different payment method - Or customer can contact support for currency exchange

Customer Has Multiple Wallets for Same Currency

Problem: Database shows customer with 2+ USD wallets

Solution: - This shouldn't happen with proper validation - Manually consolidate: Transfer balance from one to another - Deactivate or delete duplicate wallet - Contact support if issue persists

Deposits Go to Wrong Currency

Problem: Customer deposited to EUR wallet but money went to USD

Cause: Customer selected wrong currency during deposit request

Solution: - Admin can manually correct by: 1. Deducting from incorrect wallet 2. Adding to correct wallet 3. Noting correction in transaction descriptions

Disabling Multi-Currency Wallets

To disable multi-currency support:

  1. Go to System Settings → Advanced Tab
  2. Toggle "Enable Multi-Currency Wallets" to OFF
  3. Click Save changes

Important Consequences: - Existing currency-specific wallets remain in database - Customers lose ability to create new currency-specific wallets - Existing balances are NOT affected or deleted - Deposit/withdrawal requests will no longer show currency selection - System defaults to base currency for new transactions

Recommendation: Only disable if you're certain you won't need multi-currency support, as re-enabling it requires reconfiguration.

Enabling Wallet Payments at Checkout

While the wallet system manages customer balances, to allow customers to pay with their wallet during checkout, you must enable the User Wallet payment method:

Step 1: Navigate to Payment Methods

Go to Delivery & Payments > Payment Methods from the sidebar.

Step 2: Create or Edit Payment Method

Option A: Create New Payment Method

  1. Click "New Payment Method" button
  2. Fill in the basic information:
  3. Name: "User Wallet" (internal identifier)
  4. Display Name: "Pay with Wallet" or "Wallet Balance" (shown to customers)
  5. Description: "Pay using your wallet balance. Fast and secure payment method for registered users."
  6. Logo: Upload a wallet icon (optional)
  7. Enabled: Toggle ON

  8. Sort Order: Set display order (e.g., 10)

  9. In the Plugin Configuration section:

  10. Payment Plugin: Select "User Wallet" from the dropdown

  11. Click Create to save

Option B: Edit Existing Wallet Payment Method

  1. Find the existing "User Wallet" payment method in the list
  2. Click Edit
  3. Toggle Enabled to ON
  4. Adjust display name, description, or sort order as needed
  5. Click Save

Step 3: Verify Configuration

The User Wallet plugin requires no additional configuration:

  • No API keys needed
  • No webhook setup required
  • Always has valid configuration

You can click the Test button to verify the payment method is configured correctly (though this always succeeds for User Wallet).

How Wallet Payments Work

Once enabled, the payment flow works as follows:

  1. Customer adds items to cart and proceeds to checkout
  2. Payment method selection: "Pay with Wallet" appears as an option
  3. Balance check: System verifies customer has sufficient wallet balance
  4. Payment processing:
  5. If sufficient balance: Payment succeeds, wallet is debited
  6. If insufficient balance: Error shown with current balance and topup option
  7. Transaction recording: All wallet payments are automatically recorded in Wallet Transactions

Important Notes

  • Authentication Required: Only logged-in users can pay with wallet
  • Sufficient Balance: Customers must have enough balance to cover the order total
  • Multi-Currency: Wallet currency must match order currency
  • Automatic Refunds: If an order is refunded, the amount is automatically credited back to the wallet
  • Transaction History: All wallet payments create permanent transaction records

Disabling Wallet Payments

To stop accepting wallet payments:

  1. Go to Delivery & Payments > Payment Methods
  2. Find the "User Wallet" payment method
  3. Click the Enabled toggle to turn it OFF (or click Edit and disable)
  4. Customers will no longer see wallet as a payment option at checkout

Note: Disabling wallet payments does not affect existing wallet balances or transaction history—customers can still view their wallets, but cannot use them for new purchases.

Configure wallet visibility in System Settings: