Setup Wizard
The WalletPro Setup Wizard guides you through the minimum configuration required to launch a working wallet program in your store. Running the wizard before going live prevents common misconfiguration issues and ensures customers can top up, pay, and earn rewards without errors.
Overview
After activating WalletPro, a notice appears in the WordPress admin directing you to the wizard. You can also launch it at any time from WooCommerce > WalletPro > Setup Wizard.
The wizard walks through six steps:
- Currency & Wallet Behavior
- Top-Up Options
- Cashback & Rewards
- Spending Controls
- Security
- Review & Activate
None of the steps are irreversible. Every setting configured here is editable later under WooCommerce > WalletPro > Settings. The wizard is a convenience layer, not a lock-in.
You do not need to complete the wizard in a single session. WalletPro saves progress as you advance through each step. Return to WooCommerce > WalletPro > Setup Wizard to resume where you left off.
Before You Start
Have the following ready before launching the wizard:
- At least one payment gateway already configured and tested in WooCommerce (used for wallet top-ups).
- A decision on whether wallet balances will be denominated in your store's base currency or whether you need multi-currency wallets.
- An email address for scheduled financial reports if you plan to use the CSV email feature.
Step 1: Currency & Wallet Behavior
This step establishes how balances are stored and displayed.
| Setting | Description | Default |
|---|---|---|
| Wallet currency mode | Single currency (store base) or multi-currency (balance stored per currency). Multi-currency requires a compatible currency-switching plugin. | Single currency |
| Balance display format | Controls how balances appear in My Account, checkout, and emails. Uses WooCommerce currency settings by default. | Inherit from WooCommerce |
| Allow partial payments | Customers can pay part of an order with wallet credit and cover the remainder with another payment method. | Enabled |
| Minimum wallet payment | Lowest amount (in store currency) a customer can apply from their wallet to a single order. Leave blank to allow any amount down to the smallest currency unit. | None |
| Apply wallet credit automatically | Pre-checks the "Pay with wallet" option at checkout if the customer has a balance. The customer can still uncheck it. | Disabled |
Step 2: Top-Up Options
Top-ups are purchases whose sole purpose is adding funds to a wallet. This step controls how customers can load funds.
| Setting | Description | Default |
|---|---|---|
| Enable top-up product | WalletPro creates a virtual WooCommerce product used as the top-up vehicle. Customers purchase it and the amount credits their wallet immediately on payment. | Enabled |
| Top-up product name | The product title shown to customers. Defaults to "Add Wallet Funds". | Add Wallet Funds |
| Preset amounts | Comma-separated list of suggested top-up values shown as quick-select buttons on the top-up form (e.g. 10,25,50,100). Customers can also type a custom amount. |
10, 25, 50, 100 |
| Minimum top-up amount | Prevents processing very small top-up transactions that may not cover gateway fees. | 5.00 |
| Maximum top-up amount | Per-transaction cap on a single top-up. Leave blank to impose no limit. | None |
| Allowed gateways for top-up | Restricts which enabled WooCommerce payment gateways appear on the top-up form. By default all active gateways are allowed. | All active gateways |
| Auto-reload threshold | When a customer's balance falls below this amount, WalletPro automatically initiates a top-up using their saved payment method. Leave blank to disable auto-reload. | Disabled |
| Auto-reload amount | Amount added when auto-reload triggers. Only relevant when auto-reload threshold is set. | 25.00 |
Auto-reload requires that the customer's chosen gateway supports tokenized/saved payment methods. Gateways that do not support on-demand charges will be excluded from auto-reload eligibility even if listed under "Allowed gateways for top-up".
Step 3: Cashback & Rewards
This step is optional. Skip it if you do not plan to run a rewards program on launch, every option here can be configured later.
| Setting | Description | Default |
|---|---|---|
| Enable cashback | Customers earn a percentage of each eligible order value as wallet credit. | Disabled |
| Cashback rate (%) | Percentage of the order subtotal (post-discount, pre-tax by default) awarded as wallet credit. | 2 |
| Cashback on orders paid with wallet | Whether to award cashback when the customer pays entirely from their wallet balance. Disabling this prevents double-dipping. | Disabled |
| Enable milestone rewards | Award a one-time wallet credit when a customer's cumulative spend crosses a defined threshold. | Disabled |
| Enable referral program | Customers receive a referral link. When a referred customer completes their first order, both parties receive wallet credit. | Disabled |
| Referrer reward | Wallet credit awarded to the referring customer on a successful referral conversion. | 5.00 |
| Referee reward | Wallet credit awarded to the newly referred customer after their first qualifying order. | 5.00 |
Step 4: Spending Controls
Spending controls limit how much wallet credit a customer can use within a defined period, helping merchants manage liability and fraud exposure.
| Setting | Description | Default |
|---|---|---|
| Maximum wallet balance | Per-customer cap on the total balance they can hold. Prevents accumulation beyond this amount via top-up or reward credit. | None |
| Daily spend limit | Maximum wallet credit a customer can apply to orders within a rolling 24-hour window. | None |
| Weekly spend limit | Maximum wallet credit applicable across a rolling 7-day window. | None |
| Monthly spend limit | Maximum wallet credit applicable across a rolling 30-day window. | None |
| Apply limits per role | Override global limits with role-specific rules. For example, wholesale customers may have higher caps than retail. Configured as a table of WP user roles mapped to limit values. | Disabled |
| Credit expiry | Number of days after which unused wallet credit expires. Expired credit is logged and reportable as breakage. Leave blank to disable expiry. | None |
Step 5: Security
| Setting | Description | Default |
|---|---|---|
| Step-up authentication for withdrawals | Requires customers to confirm their password (or complete a second factor if configured) before initiating a wallet withdrawal to an external method. | Enabled |
| Step-up authentication for transfers | Requires password re-entry before a customer can transfer balance to another customer. | Enabled |
| KYC gate | Require customers to complete identity verification (via your configured KYC integration) before topping up or transferring above a threshold amount. | Disabled |
| KYC threshold amount | Single-transaction amount above which KYC verification is required. Only applies when KYC gate is enabled. | 200.00 |
| Rate-limit redemption codes | Maximum number of code redemption attempts per customer per hour before the customer is temporarily blocked from further attempts. | 10 per hour |
| HMAC audit ledger | Enables tamper-evident chaining of the transaction ledger. Each ledger entry includes an HMAC signature that references the previous entry, making silent modification detectable. This should remain enabled in production. | Enabled |
Disabling the HMAC audit ledger removes the tamper-evident property of your transaction history. This is only appropriate in staging environments. Do not disable it in production if you intend to use ledger exports for accounting or dispute resolution.
Step 6: Review & Activate
The final step displays a summary of all choices made in the previous steps. Review each section before clicking Activate WalletPro.
When you activate:
- WalletPro applies the wizard settings to the database.
- The top-up product is created (if enabled) and published.
- The Wallet section appears in the customer's My Account page.
- The WalletPro admin menu items become fully functional.
A confirmation notice appears at the top of the screen with links to the admin balances overview and the documentation index.
Wizard Settings vs. Full Settings
The wizard covers the most commonly needed options. The full settings panel at WooCommerce > WalletPro > Settings exposes additional options not shown during initial setup, including:
- Gift credit rules and gift amount caps
- Redemption code batch configuration
- Webhook endpoints and signing secrets
- REST API key management
- Scheduled CSV email recipients and frequency
- WooCommerce Analytics integration toggles
- Program ROI and cohort analytics settings
Re-Running the Wizard
Navigate to WooCommerce > WalletPro > Setup Wizard at any time to run the wizard again. It pre-populates all fields with current values, so you can use it as a guided configuration editor rather than starting from scratch.
If you are migrating from another store credit plugin, run the wizard first to establish baseline settings, then use WooCommerce > WalletPro > Import to bring in existing customer balances. Importing before completing the wizard can cause balances to import with incorrect expiry or currency settings.
Verifying the Setup
After activating the wizard, confirm the following before opening the wallet program to customers:
- Navigate to your store front end and log in as a test customer. Confirm the Wallet tab appears under My Account.
- Add a small amount using the top-up form and verify the balance updates immediately.
- Add a product to the cart and confirm the wallet payment option appears at checkout.
- Place a test order using wallet credit and verify the balance decreases by the correct amount.
- In the admin, go to WooCommerce > WalletPro > Balances and confirm the test customer's balance and transaction ledger are accurate.
- If cashback is enabled, confirm the test order triggered a pending cashback credit visible in the ledger.
If any step produces unexpected behavior, check WooCommerce > Status > Logs and filter by walletpro for diagnostic output.
WP-CLI Equivalent
For headless or CI environments, WalletPro exposes the wizard's core activation step via WP-CLI:
# Apply a set of WalletPro options from a JSON config file and activate
wp wallet setup --from-json=/path/to/walletpro-config.json
# Run the built-in health check after setup to verify the configuration
wp wallet doctor
The wp wallet doctor command checks gateway compatibility, ledger integrity, and required database tables. It outputs a pass/fail report for each check and exits with a non-zero code if any critical check fails, making it suitable for use in deployment pipelines.
See the WP-CLI reference for the full list of wp wallet setup parameters and the JSON config schema.