# Admin Settings Overview
Source: https://docs.standalonetech.com/admin-guide/settings
A detailed guide to the TeraWallet configuration options in your WordPress admin.
The TeraWallet settings are divided into multiple tabs, each controlling specific aspects of the wallet behavior. Navigate to **TeraWallet** > **Settings** to access these options.
### General Settings
This tab controls the fundamental behavior of the wallet system.
* **Enable Partial Payment**: When active, customers can use their wallet balance for a portion of the total order.
* **Is auto deduct for partial payment**: Automatically applies the customer's wallet balance as a discount if partial payment is enabled.
* **Tax treatment** *(new in 1.6.4)*: Choose **Wallet pays goods only** (default) or **Wallet pays the whole order including tax**. See [Partial & Combined Payments](/user-guide/partial-payments#tax-treatment).
* **Deduct wallet balance** *(new in 1.6.4)*: Deduct the wallet portion **at order placement** (default) or **when payment completes**.
* **Refund wallet on partial refunds** *(new in 1.6.4)*: Return a proportional share of the wallet payment when a partial WooCommerce refund is issued. On by default.
* **Enable Wallet Transfer**: Allow users to transfer funds to other registered customers using their email address.
* **Minimum/Maximum Transfer Amount**: Bound how much a customer can send in a single transfer.
* **Transfer Charge**: Optionally set a fixed or percentage-based charge for each fund transfer.
* **Enable Wallet Topup**: Allow customers to add funds manually via their account dashboard.
* **Minimum/Maximum Topup Amount**: Restrict the amount a customer can add to their wallet in a single transaction.
### Credit/Cashback Settings
Configure how rewards are credited to users' wallets.
* **Cashback Rule**: Choose the calculation scope:
* **Cart Wise**: Cashback based on the total cart value.
* **Product Wise**: Cashback based on specific product settings.
* **Product Category Wise**: Cashback based on the product category rules.
* **Cashback Type**: Select **Percentage** or **Fixed Amount**.
* **Cashback Amount**: The default value for the reward.
* **Max Cashback Amount**: Caps the total reward per order to a specific limit.
* **Min Cart Amount for Cashback**: The minimum total an order must reach to qualify for any cashback.
* **Max Cashback Scope** *(new in 1.6.1)*: Apply the cap **per order** (default on new installs) or **per item**.
* **Refund Clawback** *(new in 1.6.1)*: Proportionally reverse cashback when an order is refunded (off by default), with an optional **allow negative** setting.
* **Exclude Role from Cashback**: Select user roles (e.g., Administrator, Vendor) that should not receive rewards.
* **Process Cashback Status**: Define which WooCommerce order statuses trigger the reward (e.g., Completed, Processing).
See [Cashback Rules & Priority Logic](/cashback/rules-logic) for the full calculation model.
### Transaction Descriptions
**New in 1.6.3.** A dedicated settings tab for customizing ledger entry text.
Set per-category description templates so ledger entries read the way you want. Templates support
tokens — `{order_id}`, `{amount}`, `{user_name}`, `{currency}` and `{original_details}` — and
replace the system-generated description on new transactions when configured.
### Gateway Settings
TeraWallet acts as a WooCommerce gateway. Here, you can control its visibility and fees.
* **Title/Description**: Customize what customers see at checkout.
* **Payment Method Visibility**: Hide the wallet gateway if the balance is zero or if specific products are in the cart.
* **Gateway Charges**: Apply extra fees when customers use certain gateways to top up their wallets.
### Actions Settings
Incentivize user engagement by rewarding specific site actions:
* **New User Registration**: Credit a specific amount to new users upon signing up. Since 1.6.2 this also covers users created via SSO/SAML, social login, the REST API and WP-CLI.
* **Daily Visit**: Reward users for logging in once per day.
* **Product Review**: Credit users for leaving verified reviews on your products.
* **Referrals**: Reward customers for referring visitors and sign-ups. Activity is recorded in a dedicated referrals ledger with a customer history view and an admin [Referral Report](/admin-guide/transactions#referral-report).
* **Sell Content**: Let users sell digital content and receive the proceeds into their wallet.
When configuring rewards for actions like registrations or reviews, ensure you have set limits to prevent abuse (e.g., limit daily visit rewards to once per 24 hours).
# Transaction & Ledger Management
Source: https://docs.standalonetech.com/admin-guide/transactions
How to manage user wallet balances and audit the transaction ledger.
TeraWallet provides a comprehensive transaction management system to view, audit, and manually adjust customer balances.
### Auditing the Ledger
Navigate to **TeraWallet** to view every balance modification recorded by the system. The ledger provides a detailed history, including:
* **User**: The customer associated with the transaction.
* **Type**: Indicates whether it was a **Credit** (funds added) or **Debit** (funds removed).
* **Amount**: The transaction value.
* **Balance**: The user's total balance *after* the transaction was recorded.
* **Details**: A system-generated or admin-provided description (e.g., "Cashback for Order #123" or "Manual credit by Admin").
* **Date**: The timestamp of the transaction.
### Manual Credit/Debit
As an administrator, you can manually adjust a user's wallet balance.
1. Go to **TeraWallet**.
2. Select the **Customer** by searching for their username or email.
3. Hover over the user and click **Edit Balance** to access edit transaction popup window.
4. Choose the **Transaction Type** (Credit or Debit).
5. Enter the **Amount**.
6. Provide a **Description** for the ledger entry.
7. Click **Save** to apply the changes and update the user's balance.
### User Balance Management
To view all customer balances in one place:
1. Navigate to **TeraWallet**.
2. This screen shows a list of all registered users and their current wallet balance.
3. You can quickly search for a specific user to check their available funds.
4. From this screen, you can click on any user to view user's transaction history.
### Locking User Accounts
In cases of suspected fraud or dispute, you can lock a user's wallet account:
1. Edit the user profile under **Users** > **All Users**.
2. Find the **Wallet Management** section.
3. Check the **Lock Wallet** box.
4. While locked, the user cannot:
* Use their wallet balance at checkout.
* Top up their wallet.
* Receive or send transfers.
Manual adjustments to the ledger should be done carefully, as they are recorded permanently in the audit trail. Always provide a clear description for future reference.
### Bulk Credit & Debit
From the **Wallet → Users** screen you can select multiple users and apply a bulk **Credit** or
**Debit**. A popup collects the amount and description, and bulk adjustments are tagged with the
`adjustment` category. Bulk operations are idempotent per user, so a retry after an interrupted run
will not double-credit anyone.
### Deleting Transaction Logs
The **Delete Logs** bulk action opens a modal where you choose:
* **Delete mode** — **Soft** (recoverable; rows are flagged `deleted`) or **Hard** (permanent removal).
* **Balance handling** — **Keep** (insert a single balancing entry so the user's balance is
unchanged) or **Wipe** (let the balance settle to `0`).
Negative balances are preserved symmetrically when **Keep** is chosen.
### Exporting Transactions
Transaction history can be exported to CSV for accounting and audits. The export includes the typed
**category** column (`topup`, `cashback`, `partial_payment`, `transfer`, `refund`, `adjustment`, etc.).
### Referral Report
**New in 1.6.2.** Available under **TeraWallet → Referral Report**.
When the Referrals earning action is enabled, the Referral Report lists every referral with the
referrer, type, status (pending / credited / rejected) and date, plus referrer/type/status and
date-range filters, a store-wide summary header, and a filtered CSV export.
# Cashback Rules & Priority Logic
Source: https://docs.standalonetech.com/cashback/rules-logic
A deep dive into how rewards are calculated and triggered in TeraWallet.
The cashback reward program is one of the most powerful features of TeraWallet. It allows you to incentivize purchases and drive customer loyalty by offering digital balance rewards.
### Cashback Calculation Scope
TeraWallet supports three primary ways to calculate rewards:
#### 1. Cart-Wise Cashback (Global)
This rule applies to the total order value.
* **Trigger**: When an order is placed.
* **Configuration**: Set in **TeraWallet** > **Settings** > **Credit**.
* **Example**: If set to 10% and the cart total is \$1,000, the user receives \$100 cashback.
#### 2. Product-Wise Cashback (Specific)
This rule gives you granular control over individual products.
* **Configuration**: Defined on the **Product Edit** page in WooCommerce.
* **Example**: Reward \$50 for a "Premium T-shirt" but 5% for a "Luxury Watch."
* **Variable Support**: Different cashback amounts can be set for different product variations.
#### 3. Category-Wise Cashback (Taxonomy)
Apply rules to entire groups of products.
* **Configuration**: Defined in **Products** > **Categories**.
* **Conflict Handling**: If a product belongs to multiple categories with rules, you can choose whether the system should award the **Minimum** or **Maximum** available reward in the settings.
### Priority & Override Logic
When multiple rules are active, TeraWallet follows this priority:
**Product-Specific Rule > Category-Specific Rule > Global Cart Rule**.
* If a product has an individual cashback setting, that rule is used.
* If no product-level rule exists, the system checks the category rule.
* If neither exists, the global cart-wise rule is applied.
### Calculation Examples
**Example A: Percentage vs. Fixed**
* Global: 10%
* Max Cashback: \$100
* Order Total: \$2,000
* **Calculation**: 10% of \$2,000 is \$200, but since the **Max Cashback** is set to \$100, the user receives **\$100**.
**Example B: Category-Wise Override**
* Global: 5%
* "Electronics" Category: 10%
* Order Total: \$500 (Electronics items)
* **Calculation**: The user receives **\$50** (10%) instead of \$25 (5%) because the category rule has higher priority.
### When are rewards credited?
Cashback is not awarded immediately. It is triggered by order status changes.
* Go to **TeraWallet** > **Settings** > **Credit** and find **Process Cashback Status**.
* Most stores set this to **Completed** or **Processing**.
* **Flow**: Customer Pays -> Order Marked as Completed -> **Cashback Credited**.
### Cap Scope: Per Order vs Per Item
**New in 1.6.1.** Set **Max cashback scope** under **Settings → Credit**.
The **Max Cashback Amount** cap can be applied two ways:
* **Per order** *(default on new installs)* — the cap applies once to the whole cart.
* **Per item** — the cap applies to each qualifying line item.
Stores upgrading from older versions keep **per item** behavior to preserve their existing setup.
### Clawback on Refund
By default, cashback is reversed when an order is **cancelled**. You can additionally enable
**Refund clawback** under **Settings → Credit** so that cashback is clawed back **proportionally**
when an order is refunded:
* Off by default for upgrade safety — enable it explicitly.
* If the customer has already spent the credit, the default policy debits whatever balance remains
and logs the shortfall. An opt-in **allow negative** option can drive the wallet negative for an
exact reversal.
* Override the amount with the `woo_wallet_cashback_refund_clawback_amount` filter.
### Cashback Expiry
The free plugin does not enforce cashback expiry, but it exposes a seam
(`woo_wallet_cashback_expiry_timestamp`) that [TeraWallet Pro](/getting-started/pro) and add-ons use
to expire cashback after a set period. When set, the expiry is stored on the transaction and exposed
in the REST API as `cashback_expires_at`.
### Coupons as Cashback
A unique feature where standard WooCommerce coupons can be "converted" into wallet rewards.
* Create a coupon in **Marketing** > **Coupons**.
* Check the **Is coupon cashback?** box in the TeraWallet tab.
* When the customer applies this coupon, the discount is **not deducted** from the order total. Instead, the discount value is recorded and credited to the user's wallet after checkout.
Cashback is automatically clawed back when an order is cancelled. To also reverse cashback on
**partial or full refunds**, enable **Refund clawback** in the settings (see above).
# Plugin Architecture & Internals
Source: https://docs.standalonetech.com/developer-guide/architecture
A deep dive into how TeraWallet works under the hood for developers.
TeraWallet is built with a modular, object-oriented approach that prioritizes data integrity and extensibility.
### Core Architecture
* **Database-First Ledger**: Unlike many WordPress plugins that rely solely on user meta, TeraWallet uses a custom database table for all transaction records. This ensures that the wallet balance is always auditable and accurate.
* **MySQL Locking Mechanism**: To prevent race conditions during concurrent transactions (e.g., multiple simultaneous API calls or AJAX requests), TeraWallet employs **MySQL-level locking** (`GET_LOCK`) when performing credit or debit operations. Money-moving paths additionally serialize partial-payment debits and refunds with a **per-order lock** so concurrent gateway webhooks can't double-debit or double-refund.
* **Idempotent REST writes**: State-changing endpoints replay the cached response for a repeated `Idempotency-Key`, so retries never duplicate top-ups, transfers or bulk credits.
* **Singleton Lifecycle**: The main `Woo_Wallet` class (in `class-woo-wallet.php`) uses a singleton pattern to manage sub-modules like the Wallet, Cashback, API, and Settings.
### Folder Structure
* `/includes/`: The core PHP logic of the plugin.
* `class-woo-wallet-wallet.php`: Contains the `credit()`, `debit()`, and balance calculation logic.
* `class-woo-wallet-cashback.php`: Handles all reward calculations and rules.
* `class-woo-wallet-payment-method.php`: Implements the `WC_Payment_Gateway` for WooCommerce.
* `/actions/`: Modular classes for site-wide rewards (e.g., new registrations, daily visits).
* `/api/`: Controllers for the REST API integration.
* `/templates/`: Overridable UI components for the frontend dashboard and checkout.
* `/src/`: JavaScript (React/ES6) and SCSS source files for the admin and frontend interfaces.
* `/assets/`: Compiled CSS, JS, and image assets.
### Custom Database Tables
TeraWallet creates two primary tables during installation:
* `wp_woo_wallet_transactions`:
* `transaction_id`: Primary Key (BIGINT).
* `user_id`: The user associated with the transaction.
* `type`: Either `credit` or `debit`.
* `amount`: The transaction value.
* `balance`: The calculated balance *after* the transaction.
* `currency`: The currency code used.
* `details`: A detailed description of the entry.
* `wp_woo_wallet_transaction_meta`:
* Stores additional metadata for each transaction (e.g., associated order ID, cashback type).
* `wp_woo_wallet_referrals` *(since 1.6.2)*:
* One row per visitor or sign-up referral, with status, reward amount and the currency it was
credited in — giving referrals a full audit trail.
Since 1.6.0, the transactions table also carries per-row currency audit columns (`original_amount`,
`original_currency`, `original_rate`, `mode`), and since 1.6.3 a first-class indexed `category`
column.
### Multi-Currency
TeraWallet abstracts currency conversion behind a provider layer with first-class adapters for
**WOOCS/FOX, WPML/WCML, CURCY, Aelia and YayCurrency**, plus a generic fallback for any plugin that
filters `woocommerce_currency`. The ledger runs in one of two modes — `single_base` (one canonical
balance in the shop base currency) or `per_currency` (separate sub-balances), the latter gated by
the `woo_wallet_enable_per_currency_mode` filter. Inspect the active provider and mode at runtime via
`GET /terawallet/v1/system/multicurrency`.
### Core Transaction Flow
1. **Initiation**: A module calls `woo_wallet()->wallet->credit()` or `debit()`.
2. **Locking**: The system acquires a MySQL lock for the specific user.
3. **Calculation**: It fetches the most recent balance from the ledger.
4. **Validation**: For debits, it ensures the user has sufficient funds (unless negative transactions are allowed via filter).
5. **Recording**: A new entry is inserted into the `transactions` table.
6. **Syncing**: The `_current_woo_wallet_balance` user meta key is updated for fast read access.
7. **Hooks**: Actions like `woo_wallet_transaction_recorded` are fired.
8. **Release**: The MySQL lock is released.
The `_current_woo_wallet_balance` user meta is essentially a cache of the value in the ledger. Always use the `get_wallet_balance()` method to ensure accuracy.
# Hooks Reference (Actions & Filters)
Source: https://docs.standalonetech.com/developer-guide/hooks
A comprehensive guide to extending TeraWallet using WordPress hooks.
TeraWallet is highly extensible, offering numerous actions and filters to customize its behavior.
### Essential Filters
#### `woo_wallet_current_balance`
Modify the current wallet balance before it is returned.
* **Parameters**: `(float) $balance`, `(int) $user_id`.
* **Example**: Add a temporary 5% bonus to all balance displays.
```php theme={null}
add_filter( 'woo_wallet_current_balance', function( $balance, $user_id ) {
return $balance * 1.05;
}, 10, 2 );
```
#### `woo_wallet_payment_is_available`
Programmatically toggle the wallet payment gateway visibility.
* **Parameters**: `(bool) $is_available`.
* **Example**: Disable wallet payment for a specific product category.
#### `woo_wallet_cashback_amount`
Adjust the calculated cashback amount before it's stored.
* **Parameters**: `(float) $cashback_amount`, `(int) $order_id`.
#### `woo_wallet_disallow_negative_transaction`
Allow or disallow negative transactions for specific scenarios.
* **Parameters**: `(bool) $disallow`, `(float) $amount`, `(float) $balance`.
* **Example**: Allow a "Credit Limit" for trusted users.
```php theme={null}
add_filter( 'woo_wallet_disallow_negative_transaction', function( $disallow, $amount, $balance ) {
if ( current_user_can( 'manage_options' ) ) {
return false; // Allow admins to go negative
}
return $disallow;
}, 10, 3 );
```
### Essential Actions
#### `woo_wallet_transaction_recorded`
Fires after any successful credit or debit to the ledger.
* **Parameters**: `(int) $transaction_id`, `(int) $user_id`, `(float) $amount`, `(string) $type`.
* **Example**: Send a custom SMS notification when balance is updated.
#### `woo_wallet_payment_processed`
Fires after a successful wallet purchase.
* **Parameters**: `(int) $order_id`, `(int) $transaction_id`.
#### `woo_wallet_admin_adjust_balance`
Fires when an administrator manually edits a user's balance.
* **Parameters**: `(int) $user_id`, `(float) $amount`, `(string) $payment_type`.
#### `woo_wallet_credit_purchase_completed`
Fires when a customer completes a "Wallet Topup" order.
* **Parameters**: `(int) $transaction_id`, `(object) $order`.
### Customizing Partial Payments
#### `woo_wallet_partial_payment_amount`
Modify the amount applied as a partial payment.
* **Parameters**: `(float) $amount`.
* **Example**: Always cap partial payments to 50% of the total order.
```php theme={null}
add_filter( 'woo_wallet_partial_payment_amount', function( $amount ) {
$cart_total = WC()->cart->get_total('edit');
return min( $amount, $cart_total / 2 );
} );
```
### Recently Added Hooks (1.6.1–1.6.4)
These hooks were introduced in recent releases. Each name below was verified against the plugin
source.
| Hook | Type | Since | Purpose |
| -------------------------------------------- | ------ | ----- | --------------------------------------------------------------------------------------------------------- |
| `woo_wallet_dashboard_stat_cards` | filter | 1.6.4 | Register custom summary cards on the customer dashboard (e.g. "Total withdrawn"). |
| `woo_wallet_partial_payment_max_amount` | filter | 1.6.4 | Cap the wallet amount that can be applied to an order at checkout. |
| `woo_wallet_partial_payment_refund_amount` | filter | 1.6.4 | Override the wallet amount refunded on a partial WooCommerce refund. |
| `woo_wallet_partial_payment_debit_failed` | action | 1.6.4 | Fires when a deferred partial-payment debit fails because the balance was spent before payment completed. |
| `woo_wallet_allowed_dashboard_actions` | filter | 1.6.4 | Allow-list of dashboard tabs the `wallet_action` parameter may dispatch. |
| `woo_wallet_cashback_refund_clawback_amount` | filter | 1.6.1 | Override the cashback amount clawed back on a refund. |
| `woo_wallet_cashback_expiry_timestamp` | filter | 1.6.1 | Mark a cashback row as expiring at a given timestamp (Pro/add-on seam). |
| `woo_wallet_transaction_types` | filter | 1.6.3 | Register custom transaction categories. |
| `woo_wallet_user_transactions_purged` | action | 1.6.1 | Fires after a Delete Logs purge completes. |
| `woo_wallet_enable_per_currency_mode` | filter | 1.6.0 | Enable the per-currency ledger mode. |
#### Example: add a dashboard summary card
```php theme={null}
add_filter( 'woo_wallet_dashboard_stat_cards', function( $cards, $user_id ) {
$cards['withdrawn'] = array(
'id' => 'withdrawn',
'priority' => 80,
'tone' => 'neutral',
'icon' => 'wallet',
'label' => __( 'Total withdrawn', 'your-textdomain' ),
'value' => your_get_total_withdrawn( $user_id ),
);
return $cards;
}, 10, 2 );
```
When using hooks that modify balance or payment eligibility, always test with a non-admin user to ensure correct front-end behavior.
# REST API Reference
Source: https://docs.standalonetech.com/developer-guide/rest-api
Programmatic access to wallet balances, transactions, top-ups, transfers and admin tools via the terawallet/v1 REST API.
TeraWallet ships a first-class REST API under the **`terawallet/v1`** namespace. It powers the
plugin's own React dashboard and admin screens, and is fully available to your own apps and
integrations.
The older `wc/v3/wallet/*` routes still exist as a **deprecated** back-compatibility layer and
will be removed in a future major release. New integrations should target **`terawallet/v1`**.
## Base URL
```
https://your-store.com/wp-json/terawallet/v1/
```
## Authentication
Endpoints are grouped by who may call them, and each group uses the matching auth method:
| Group | Path prefix | Who | Authentication |
| ----------------- | ----------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------ |
| Customer | `me/*` | The logged-in customer (acts on their own wallet) | WordPress cookie + REST nonce (same-origin), e.g. an `X-WP-Nonce` header |
| Admin | `admin/*` | Users with the `manage_woocommerce` capability | Cookie + nonce, or WooCommerce **Consumer Key / Secret** (Basic Auth) |
| Settings / System | `settings/*`, `system/*` | `manage_woocommerce` | Cookie + nonce, or Consumer Key / Secret |
| Public | `public/*`, `settings/public` | Anyone | None |
For external/server-to-server calls, generate keys under **WooCommerce → Settings → Advanced →
REST API** and send them as HTTP Basic Auth.
### Idempotency
State-changing customer endpoints (`POST me/topup`, `POST me/transfer`) and admin bulk
operations honor an **`Idempotency-Key`** request header. Send a unique key (e.g. a UUID) per
logical action; a retry with the same key replays the original response instead of creating a
duplicate top-up, transfer, or credit. Keys are scoped per user with a 24-hour TTL.
***
## Customer endpoints (`me/*`)
### Get balance
```
GET /terawallet/v1/me/balance
```
Returns the current user's balance. The response is multi-currency aware: `amount` is in the
active storefront currency, while `base_*` fields are always normalized to the shop base currency.
```json theme={null}
{
"amount": 250.00,
"currency": "USD",
"formatted": "$250.00",
"base_currency": "USD",
"base_amount": 250.00,
"base_formatted": "$250.00",
"mode": "single_base",
"balances": [
{ "currency": "USD", "amount": 250.00, "formatted": "$250.00" }
]
}
```
| Field | Description |
| ----------------------------------- | -------------------------------------------------------------------------- |
| `amount` / `currency` / `formatted` | Balance in the active storefront currency. |
| `base_amount` / `base_currency` | Total wallet value normalized to the shop base currency. |
| `mode` | `single_base` or `per_currency` (see [multi-currency](#system-endpoints)). |
| `balances[]` | Per-currency sub-balances; always at least one entry. |
### List transactions
```
GET /terawallet/v1/me/transactions
GET /terawallet/v1/me/transactions/{id}
```
Paginated ledger history for the current user.
| Query arg | Type | Notes |
| ------------------ | ------- | ------------------------------------------- |
| `page`, `per_page` | integer | Standard pagination. |
| `orderby` | string | `date`, `amount`, or `transaction_id`. |
| `order` | string | `asc` or `desc`. |
| `type` | string | Filter by `credit` or `debit`. |
| `category` | string | Filter by transaction category (see below). |
Each row exposes a typed **`category`**, one of: `topup`, `cashback`, `cashback_adjustment`,
`cashback_refund`, `partial_payment`, `transfer`, `refund`, `adjustment`, `other`.
### Create a top-up
```
POST /terawallet/v1/me/topup
```
Creates a top-up order and returns a payment URL to redirect the customer to.
| Body field | Type | Required | Notes |
| ---------------- | ------ | -------- | --------------------------------------------------- |
| `amount` | number | Yes | Minimum `0.01`. |
| `payment_method` | string | No | A WooCommerce gateway id (e.g. `stripe`). |
| `currency` | string | No | ISO 4217 code; charges the top-up in that currency. |
```json theme={null}
{
"order_id": 1234,
"amount": 50.00,
"currency": "USD",
"payment_url": "https://your-store.com/checkout/order-pay/1234/?pay_for_order=true&key=wc_order_..."
}
```
Send an `Idempotency-Key` header so a double-submit (or a network retry) returns the original
order instead of creating a second top-up.
### Transfer funds
```
POST /terawallet/v1/me/transfer
GET /terawallet/v1/me/transfer/recipients
```
Send wallet balance to another registered user. Provide **either** `recipient_id` **or**
`recipient_email`.
| Body field | Type | Required | Notes |
| ----------------- | ------- | --------------- | ------------------------------------------------------ |
| `recipient_id` | integer | One of id/email | Recipient user id. |
| `recipient_email` | string | One of id/email | Recipient account email. |
| `amount` | number | Yes | Subject to the configured min/max and transfer charge. |
| `note` | string | No | Optional message stored on both ledger legs. |
| `currency` | string | No | Optional ISO 4217 code. |
The `recipients` route returns a lookup list for an autocomplete picker (gated by a filter).
### Other customer reads
| Endpoint | Returns |
| -------------------------------------- | ---------------------------------------------------------------------- |
| `GET /terawallet/v1/me` | Profile snapshot with wallet summary and related links. |
| `GET /terawallet/v1/me/referrals` | The customer's referral share URL, visitor/signup counts and earnings. |
| `GET /terawallet/v1/me/cashback-rules` | The cashback rules currently active for this customer/cart. |
***
## Admin endpoints (`admin/*`)
Require the `manage_woocommerce` capability.
### Transactions
```
GET /terawallet/v1/admin/transactions
POST /terawallet/v1/admin/transactions
GET /terawallet/v1/admin/transactions/{id}
PATCH /terawallet/v1/admin/transactions/{id}
DELETE /terawallet/v1/admin/transactions/{id}?force=true
POST /terawallet/v1/admin/transactions/bulk
```
List supports `page`, `per_page`, `orderby` (`id`, `transaction_id`, `date`, `amount`,
`currency`, `type`, `user_id`), `order`, and `type` filters.
Create a manual credit or debit:
```json theme={null}
{
"user_id": 42,
"type": "credit",
"amount": 10.00,
"details": "Goodwill credit"
}
```
`DELETE` performs a soft delete by default; pass `?force=true` for a permanent delete. The
`bulk` route accepts an `action` of `credit`, `debit`, or `delete` and is idempotent per user.
### Users
```
GET /terawallet/v1/admin/users
GET /terawallet/v1/admin/users/{id}
POST /terawallet/v1/admin/users/{id}/lock
POST /terawallet/v1/admin/users/{id}/unlock
```
List users with their balances, read a single user, and lock/unlock a wallet to block further
spending (useful for fraud holds).
### Admin transfer
```
POST /terawallet/v1/admin/transfer
```
Move balance between two users on the customer's behalf.
***
## Settings & system endpoints
| Endpoint | Description |
| ----------------------------------------- | ------------------------------------------------------------------- |
| `GET /terawallet/v1/settings` | Fetch all plugin settings. |
| `POST /terawallet/v1/settings/section` | Save a settings section (`section_id` + fields). |
| `POST /terawallet/v1/settings/js-section` | Save a JS-registered settings tab (sanitized per server whitelist). |
| `GET /terawallet/v1/system/multicurrency` | Active currency provider, base/active currencies and ledger mode. |
| `GET /terawallet/v1/settings/public` | Unauthenticated public settings (e.g. cashback rules). |
All responses are JSON. Send `Content-Type: application/json` on requests with a body, and an
`Idempotency-Key` header on top-ups, transfers and bulk operations.
## Legacy namespace (deprecated)
The `wc/v3/wallet/*` routes from earlier versions remain as thin proxies for back-compatibility
and emit the same row shapes as their `terawallet/v1` equivalents. **Do not build new
integrations against them** — migrate to `terawallet/v1`.
# Troubleshooting & FAQ
Source: https://docs.standalonetech.com/faq/troubleshooting
Common issues and solutions for TeraWallet.
### Common Issues
#### Wallet Payment Method is Not Visible at Checkout
If the "Wallet" payment method doesn't appear for customers:
1. **Low Balance**: The wallet method is hidden by default if the customer's balance is lower than the order total (unless partial payment is enabled).
2. **Settings**: Go to **WooCommerce** > **Settings** > **Payments** and ensure "TeraWallet" is enabled.
3. **Guest Checkout**: Wallet payments require a registered account. It will not show for guests unless they log in or create an account.
4. **Top-up Item**: The wallet gateway is disabled if the customer is purchasing a "Wallet Topup" product.
#### Cashback Not Applying to Orders
If cashback is not credited after a purchase:
1. **Order Status**: Check the "Process Cashback Status" in **TeraWallet** > **Settings** > **Credit**. The reward is only credited when the order reaches that specific status (e.g., Completed).
2. **User Role**: Ensure the customer's role is not in the "Exclude Role" list in settings.
3. **Product Rule**: If you're using product-wise rules, verify that the individual product has a cashback amount set.
4. **Rechargeable Order**: Cashback is never awarded for "Wallet Topup" purchases.
#### Partial Payment Option is Missing
1. **Enable Setting**: Ensure "Enable Partial Payment" is checked in **TeraWallet** > **Settings** > **General**.
2. **Zero Balance**: The option won't appear if the customer has a \$0 balance.
3. **Full Balance**: If the customer has enough balance to cover the *entire* order, they should use the "Wallet" gateway instead of partial payment.
#### Tax Stays on the Full Order with Partial Payment
By default the wallet pays for **goods only**, so tax is still charged on the order — this is correct
when wallet top-ups are not taxed when loaded. If your top-ups *are* taxed at load and you want the
wallet to cover tax too, set **Tax treatment** to **Wallet pays the whole order including tax** under
**Settings → General → Partial Payment**. See [Partial & Combined Payments](/user-guide/partial-payments#tax-treatment).
#### Balance Shows Funds but Checkout Says "Insufficient"
On single-currency stores that previously ran in multi-currency mode, the displayed balance and the
spendable balance could diverge. TeraWallet 1.6.4 ships a **one-time upgrade** that normalizes any
leftover non-base ledger rows into the store base currency, so the two figures agree again. If you
just upgraded, reload the wallet page once to let the upgrade run.
### Frequently Asked Questions
#### Can I delete the "Wallet Topup" product?
**No**. This product is required for the top-up feature to work. Deleting it will break the ability for customers to add funds. If deleted by mistake, deactivate and reactivate the plugin to recreate it.
#### Does TeraWallet support multi-currency?
Yes, TeraWallet is compatible with popular multi-currency plugins like **WOOCS** and **WPML Multi-currency**. It records transactions in the site's default currency and handles conversions automatically during checkout.
#### Can I manually edit a user's balance?
Yes. Go to **TeraWallet** > **Transactions** and click **Add New** to manually credit or debit any user's account.
#### Is there a limit to how much a user can store?
By default, there is no limit to the maximum balance a user can hold. However, you can set limits on how much they can **top up** in a single transaction in the settings.
Still having issues? Visit our [Community Support Forum](https://standalonetech.com/forums/forum/terawallet/) or check the WordPress.org support threads.
# Initial Configuration
Source: https://docs.standalonetech.com/getting-started/configuration
Setting up TeraWallet for the first time.
After activating the TeraWallet plugin, you need to configure it to suit your store's requirements.
### Accessing Settings
Navigate to **TeraWallet** > **Settings** in your WordPress dashboard to access all configuration options.
### General Setup
In the **General** tab, you can manage core features:
* **Enable Partial Payment**: When enabled, customers can use their wallet balance to pay for part of an order and use another payment method for the remainder.
* **Enable Wallet Transfer**: Allow customers to send wallet balance to other registered users.
* **Top-up Minimum/Maximum**: Set limits for how much a customer can add to their wallet at once.
### Required WooCommerce Settings
To ensure the wallet functions correctly as a payment method:
1. Go to **WooCommerce** > **Settings** > **Payments**.
2. Locate **TeraWallet** in the list of payment methods.
3. Toggle the switch to **Enable** it.
4. Click **Finish set up** to customize the title and description seen by customers at checkout.
### Wallet Recharge Product
TeraWallet automatically creates a hidden "Wallet Topup" product used for adding funds.
* **Do not delete** this product.
* The product is set as **Virtual** and **Private** so it doesn't appear in your shop catalog.
* You can find it under **Products** > **All Products** if you need to troubleshoot top-up issues.
If you delete the "Wallet Topup" product, customers will not be able to add funds to their wallet. The plugin will attempt to recreate it upon the next activation.
# Installation
Source: https://docs.standalonetech.com/getting-started/installation
How to install and activate the TeraWallet plugin on your WordPress site.
TeraWallet (formerly WooWallet) is a digital wallet system for WooCommerce. It allows customers to store funds, earn rewards, and use their balance for checkouts.
### Requirements
Before installing TeraWallet, ensure your environment meets these minimums:
* **WordPress** 6.4 or higher
* **WooCommerce** 7.2 or higher (latest recommended)
* **PHP** 7.4 or higher
### Automatic Installation
The easiest way to install TeraWallet is through the WordPress admin dashboard:
1. Log in to your WordPress dashboard.
2. Navigate to **Plugins** > **Add New**.
3. In the search bar, type `TeraWallet`.
4. Find **TeraWallet** by StandaloneTech and click **Install Now**.
5. Once the installation is complete, click **Activate**.
### Manual Installation
If you prefer manual installation:
1. Download the plugin ZIP file from the [WordPress Plugin Repository](https://wordpress.org/plugins/woo-wallet/).
2. Log in to your WordPress dashboard.
3. Navigate to **Plugins** > **Add New** > **Upload Plugin**.
4. Choose the downloaded ZIP file and click **Install Now**.
5. After installation, click **Activate Plugin**.
### Verification
Once activated, you will see a new **TeraWallet** menu item in your WordPress admin sidebar.
If you don't see the TeraWallet menu, ensure that WooCommerce is installed and active.
# Key Features
Source: https://docs.standalonetech.com/getting-started/key-features
An at-a-glance tour of everything TeraWallet can do — wallet top-ups, partial payments, cashback, transfers, earning actions and more.
TeraWallet turns WooCommerce into a full digital-wallet platform. Here's the complete picture,
with links to the deep-dive guide for each capability.
## Money in, money out
Customers add funds through any WooCommerce payment gateway. Set min/max amounts and optional
per-gateway charges.
Pay part of an order from the wallet and the rest with another gateway, with full control over
tax treatment, refund behavior and debit timing.
Customers send balance to other registered users, with configurable minimums and transfer fees.
Native WooCommerce refunds credit the wallet automatically — full cancellations and proportional
partial refunds alike.
## Rewards & engagement
Reward customers cart-wise, product-wise or category-wise, with per-order or per-item caps and
optional clawback on refund.
Credit the wallet for daily visits, new registrations, product reviews, referrals, and selling
content.
A dedicated referrals ledger with customer history and an admin Referral Report.
Convert standard WooCommerce coupons into wallet rewards instead of direct discounts.
## Operations & platform
An append-only, SQL-locked transaction ledger that stays accurate under heavy concurrency.
Adapters for WOOCS/FOX, WPML/WCML, CURCY, Aelia and YayCurrency, with per-row currency audit
columns.
The `terawallet/v1` API for balances, transactions, top-ups, transfers and admin tooling.
A rich set of actions and filters for deep customization and marketplace integrations.
Looking for withdrawals, wallet expiry, importers or AffiliateWP integration? Those live in
[TeraWallet Pro](/getting-started/pro).
# TeraWallet Free vs Pro
Source: https://docs.standalonetech.com/getting-started/pro
Compare the free TeraWallet plugin with TeraWallet Pro — withdrawals, wallet expiry, wallet coupons, the importer and AffiliateWP integration.
The free TeraWallet plugin is a complete wallet system on its own. **TeraWallet Pro** is an
optional add-on that unlocks advanced money-out and lifecycle features.
## Feature comparison
| Capability | Free | Pro |
| ------------------------------------------------------------------------------------------------ | :--: | :-: |
| Wallet top-ups via WooCommerce gateways | ✅ | ✅ |
| Partial & combined payments | ✅ | ✅ |
| Cashback (cart / product / category) | ✅ | ✅ |
| Peer-to-peer transfers | ✅ | ✅ |
| Earning actions & referrals | ✅ | ✅ |
| Multi-currency support | ✅ | ✅ |
| REST API & developer hooks | ✅ | ✅ |
| **[Wallet Withdrawal](/pro/withdrawal)** — customers cash out to bank/payment methods | — | ✅ |
| **[Credit Expiry & FIFO](/pro/wallet-expiry)** — expire credit on a schedule, spend oldest first | — | ✅ |
| **[Wallet Coupons](/pro/wallet-coupons)** — coupons redeemable directly into the wallet | — | ✅ |
| **[Bulk Importer](/pro/importer)** — bulk-import balances & history from CSV | — | ✅ |
| **[AffiliateWP Integration](/pro/affiliatewp)** — pay affiliate commissions to the wallet | — | ✅ |
## Activating Pro
When the TeraWallet Pro plugin is installed and activated, a **Go Pro / Extensions** page appears
in the TeraWallet admin menu. Enter and activate your license key there to receive updates and
unlock the Pro features. See [Installation & Licensing](/pro/installation) for the full walkthrough.
Full documentation for every Pro feature.
See pricing and buy on StandaloneTech.
# TeraWallet (WooWallet) Documentation
Source: https://docs.standalonetech.com/index
The official developer and user documentation for the leading WooCommerce wallet system.
![Hero Light]()
TeraWallet is a powerful, digital wallet system for WooCommerce that allows customers to store funds, earn rewards through various site activities, and use their balance for fast, secure checkouts.
### Core Features
Secure transaction history with atomic credits and debits for every user.
Reward customers based on cart total, product categories, or specific products.
Allow customers to combine wallet funds with other payment gateways at checkout.
Extensible architecture with a rich set of actions and filters for deep integration.
### Navigation
To get started with TeraWallet, choose the guide most relevant to your role:
* **[Administrators](/admin-guide/settings)**: Learn how to configure rules, manage user balances, and audit transactions.
* **[Customers](/user-guide/wallet-dashboard)**: Understand how to top up, transfer, and pay with your wallet.
* **[Developers](/developer-guide/architecture)**: Dive into the plugin internals, hooks reference, and REST API endpoints.
### Quick Links
# AffiliateWP Integration
Source: https://docs.standalonetech.com/pro/affiliatewp
Pay AffiliateWP commissions directly into the TeraWallet balance, crediting on paid referrals and reversing on refunds.
The AffiliateWP module bridges your affiliate program and your store's wallet economy: affiliates can
receive their commissions as wallet balance instead of an external payout.
This module requires the **AffiliateWP** plugin to be installed and active. Without it, the module
silently stays dormant.
## How it works
* A new **Wallet Payout** method is added to AffiliateWP (via the `affwp_payout_methods` filter).
* Affiliates **opt in** to wallet payouts from their affiliate dashboard.
* When a referral is marked **Paid**, the commission is **credited** to the affiliate's wallet.
* If a referral is later **reversed** (e.g. the order is refunded), the corresponding amount is
**debited** back out automatically, keeping balances accurate.
## Setup
1. Install and activate **AffiliateWP** and **TeraWallet Pro**.
2. The **Wallet Payout** option becomes available in AffiliateWP automatically.
3. Affiliates choose **Wallet Payout** as their preferred payout method in their dashboard.
From then on, commission crediting and reversal happen automatically as referral statuses change.
Wallet payouts pair well with [Wallet Coupons](/pro/wallet-coupons) and
[Credit Expiry](/pro/wallet-expiry) to build a complete affiliate-loyalty loop — reward
ambassadors with store credit they're encouraged to spend.
# Pro Hooks & REST API
Source: https://docs.standalonetech.com/pro/hooks
Developer reference for TeraWallet Pro — module hooks, withdrawal/coupon/import filters, and the Pro REST endpoints.
This page covers the developer surface added by **TeraWallet Pro**. For the core plugin's hooks and
API, see the free [Hooks Reference](/developer-guide/hooks) and [REST API Reference](/developer-guide/rest-api).
## Hooks
Each name below was verified against the Pro plugin source.
| Hook | Type | Module | Purpose |
| ------------------------------------------------ | ------ | ------------- | ------------------------------------------------------------------------------------- |
| `woo_wallet_withdrawal_loaded` | action | Withdrawal | Fires when the withdrawal module is ready. |
| `woo_wallet_withdrawal_payment_gateways` | filter | Withdrawal | Register or remove payout gateways. |
| `woo_wallet_withdrawal_payment_gateway_settings` | filter | Withdrawal | Modify a gateway's settings fields. |
| `woo_wallet_withdrawable_amount` | filter | Withdrawal | Control how much a user is allowed to withdraw. |
| `woo_wallet_withdrawal_gateway_charge` | filter | Withdrawal | Override the calculated per-gateway processing fee. |
| `woo_wallet_coupons_loaded` | action | Coupon | Fires when the coupon system is initialized. |
| `woo_wallet_current_balance` | filter | Credit Expiry | Core filter the expiry module uses (priority 999) to exclude expired/redeemed credit. |
| `woo_wallet_import_batch_size` | filter | Importer | Adjust the number of CSV rows processed per batch. |
| `woo_wallet_rest_check_permissions` | filter | Importer | Override the capability check on Pro REST endpoints. |
| `affwp_payout_methods` | filter | AffiliateWP | Inject the "Wallet Payout" method into AffiliateWP. |
### Example: cap the withdrawable amount
```php theme={null}
add_filter( 'woo_wallet_withdrawable_amount', function( $amount, $user_id ) {
// Never allow withdrawing more than 500 at a time.
return min( (float) $amount, 500 );
}, 10, 2 );
```
## REST API
Pro adds endpoints under two namespaces. Verify exact routes/args against the plugin source before
building against them.
### Coupons — `terawallet/v1/coupons`
Full CRUD plus **bulk create** and **code generation** for wallet coupons. Used by the in-admin bulk
generator and available for your own automation. Requires the appropriate management capability.
### Importer — `woo-wallet-pro/v1/import`
| Route | Purpose |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| `POST /woo-wallet-pro/v1/import/upload` | Upload a CSV; returns an `import_id` (attachment id). File paths never travel through the client. |
| `POST /woo-wallet-pro/v1/import/process` | Process the next batch of rows for an import session. |
| `GET /woo-wallet-pro/v1/import/messages` | Fetch progress/result messages for a session. |
| `GET /woo-wallet-pro/v1/import/currencies` | List valid currencies for the `currency` column. |
Every import route requires `manage_options` (filterable via `woo_wallet_rest_check_permissions`),
and sessions are pinned to the uploading user.
### Withdrawal webhooks — `terawallet/v1`
Asynchronous payout webhooks for Stripe, PayPal, Razorpay, Cashfree and Paystack live under the
`terawallet/v1` namespace, with provider signature verification and replay protection. The Stripe
endpoint is `POST /wp-json/terawallet/v1/stripe/webhook` (set the webhook secret in the gateway's
settings to enable it).
# Bulk Importer
Source: https://docs.standalonetech.com/pro/importer
Import thousands of TeraWallet credit and debit transactions from a CSV file, with batch processing, per-row currency and expiry, and error logs.
The Bulk Importer loads credit and debit transactions for many users at once from a CSV file — ideal
for migrations, mass corrections, or seeding balances.
## Opening the importer
The importer is available from either:
* **Tools → Import → WooCommerce Wallet**, or
* the **Import** action on the TeraWallet users/balances screen.
It runs as a modern admin screen and requires the `manage_options` capability.
## CSV format
Headers are matched **case- and whitespace-insensitively**.
| Column | Required | Description |
| ------------- | -------- | ---------------------------------------------------------------------------------- |
| `email` | ✅ | The user's account email. |
| `amount` | ✅ | The transaction amount. |
| `type` | ✅ | `credit` or `debit`. |
| `details` | — | A description stored on the ledger entry. |
| `expire_date` | — | Optional expiry for a credit row (works with [Credit Expiry](/pro/wallet-expiry)). |
| `currency` | — | ISO 4217 code; validated against the store's WooCommerce currencies. |
A `sample.csv` is included with the plugin to use as a template. Missing required columns are
reported explicitly before processing starts.
## Processing & error handling
* **Batch processing** — large files are processed in batches in the background, so imports don't
time out. Developers can tune the batch size with the `woo_wallet_import_batch_size` filter.
* **Per-row currency** — each row's `currency` is forwarded to the ledger; core's currency manager
handles conversion or per-currency storage transparently.
* **Per-row expiry** — when `expire_date` is supplied on a credit row, it is applied to that exact
transaction (and takes precedence over the global Credit Expiry default).
* **Error reporting** — rows that fail (for example, a non-existent user email) are listed in a
detailed log so you can fix and re-import them.
Imports move real money in the ledger. Test with a small CSV first, and double-check the `type`
column — `debit` rows reduce balances.
# TeraWallet Pro
Source: https://docs.standalonetech.com/pro/index
Overview of TeraWallet Pro — withdrawals, wallet coupons, credit expiry, bulk importer and AffiliateWP integration for WooCommerce.
**TeraWallet Pro** is a premium add-on for the free [TeraWallet](/getting-started/key-features) core
plugin. It adds the money-out and lifecycle features that turn a store wallet into a full digital
economy: customer withdrawals, wallet-only coupons, automatic credit expiry, bulk balance imports,
and AffiliateWP payouts.
Pro **requires the free TeraWallet core plugin** to be installed and active — it extends core and
cannot run on its own. See [Free vs Pro](/getting-started/pro) for a side-by-side comparison.
## What you unlock
Let customers cash out their balance to PayPal, Stripe, Razorpay, Paystack, Cashfree or bank
transfer, with admin approval and per-gateway fees.
Create coupons that credit the wallet instead of discounting the cart, with email/domain limits,
usage caps and expiry.
Expire store credit on a schedule, spend the soonest-to-expire credit first, and send reminder
and lapse emails.
Import thousands of credit/debit transactions from a CSV with batch processing and error logs.
Pay affiliate commissions straight into the wallet, crediting on paid referrals and reversing on
refunds.
Activate your license for automatic updates and support.
## Requirements
| Requirement | Version |
| ----------------- | ------------------------------------- |
| TeraWallet (core) | Required, latest recommended |
| WordPress | 6.0 or higher |
| WooCommerce | 7.0 or higher |
| PHP | 7.4 or higher (8.2+ recommended) |
| AffiliateWP | Optional — only for affiliate payouts |
This section documents **TeraWallet Pro 1.0.6**. For core plugin features, see the
[Getting Started](/getting-started/key-features) and [Guides](/user-guide/wallet-dashboard)
sections.
# Installation & Licensing
Source: https://docs.standalonetech.com/pro/installation
How to install TeraWallet Pro, activate your license for updates, and configure the Pro modules.
TeraWallet Pro installs alongside the free core plugin and adds its settings into the existing
TeraWallet admin.
## Before you start
Make sure **TeraWallet (core)** is installed and **active** first. Pro declares core as a required
plugin and none of its modules load without it.
## Install the add-on
1. Purchase TeraWallet Pro from [StandaloneTech](https://standalonetech.com/product/woocommerce-wallet-pro/)
and download the plugin ZIP.
2. In WordPress, go to **Plugins → Add New → Upload Plugin**.
3. Choose the `woo-wallet-pro` ZIP and click **Install Now**.
4. Click **Activate**.
After activation, the Pro modules appear inside **TeraWallet → Settings** (a new **Withdrawal** tab,
plus **Wallet Coupon** and **Credit Expiry** options), and an **Import** entry is added for bulk
balance management.
If you previously used the standalone add-ons (Wallet Withdrawal, Wallet Coupons, Wallet Importer,
Credit Expiry, AffiliateWP for TeraWallet), **deactivate them** after installing Pro — it bundles
all of them and will warn you if any are still active.
## Activate your license
A valid license unlocks **automatic updates** and support.
1. Go to the TeraWallet **Extensions / Go Pro** page in the admin menu.
2. Enter your **license key** from your StandaloneTech account.
3. Click **Activate**.
Once activated, plugin updates appear in **Dashboard → Updates** like any other plugin. Deactivating
the license on a site frees the activation for use elsewhere.
## Next steps
Enable payout gateways and the minimum/maximum withdrawal amounts.
Set a global expiry duration and optional per-category rules.
Build coupons that top up the wallet on redemption.
Bulk-load credits and debits from a CSV file.
# Pro Settings Reference
Source: https://docs.standalonetech.com/pro/settings
Every TeraWallet Pro setting in one place — withdrawal, wallet coupon and credit expiry options and where to find them.
TeraWallet Pro adds its settings into the existing **TeraWallet → Settings** screen. This page is a
quick reference; each setting is explained in depth on its feature page.
## Withdrawal
Found on the **Withdrawal** tab. See [Wallet Withdrawal](/pro/withdrawal).
| Setting | Description |
| ------------------------------------ | -------------------------------------------------------------------- |
| **Enable Withdrawal** | Master switch for the withdrawal module. |
| **Approval Mode** | Approve requests manually, or auto-approve and pay out immediately. |
| **Minimum Withdrawal** | Smallest amount a customer may request. |
| **Maximum Withdrawal** | Largest amount a customer may request. |
| **Enable logging** | Write per-gateway debug logs, surfaced on each withdrawal screen. |
| **Enable ** | Turn an individual payout gateway on, and enter its API credentials. |
| **Enable Processing Fee** | Charge a fee per gateway (deducted from the payout). |
| **Fee Type** | `percent`, `fixed`, or `percent + fixed`. |
| **Fee Amount** / **Fixed Component** | The fee value (and the flat part for `percent + fixed`). |
## Wallet Coupon
A **Wallet Coupon** toggle plus per-coupon options on the coupon editor. See
[Wallet Coupons](/pro/wallet-coupons).
| Setting | Description |
| ------------------------------ | --------------------------------------------------------------------- |
| **Enable Wallet Coupon** | Allow coupons that credit the wallet instead of discounting the cart. |
| **Coupon value / currency** | The amount (and currency) credited on redemption. |
| **Email / domain restriction** | Limit redemption to addresses or domains (wildcards supported). |
| **Usage limits** | Global and per-user redemption caps. |
| **Expiry date** | Deadline after which the code can no longer be redeemed. |
## Credit Expiry
Found in the **Credit Expiry** options. See [Credit Expiry & FIFO](/pro/wallet-expiry).
| Setting | Description |
| --------------------------- | ---------------------------------------------------------------- |
| **Enable Credit Expiry** | Master switch for credit expiry and FIFO redemption. |
| **Credit Expire (default)** | Global duration after which new credit expires. |
| **Per-category durations** | Override the global default for specific transaction categories. |
## Importer
The [Bulk Importer](/pro/importer) has no settings tab — it's an admin screen reached from
**Tools → Import → WooCommerce Wallet** or the **Import** action on the TeraWallet users screen.
## AffiliateWP
The [AffiliateWP Integration](/pro/affiliatewp) has no settings of its own; it adds a **Wallet
Payout** method to AffiliateWP, which affiliates select in their own dashboard.
# Wallet Coupons
Source: https://docs.standalonetech.com/pro/wallet-coupons
Create coupons that credit the TeraWallet balance instead of discounting the cart, with email/domain restrictions, usage limits and expiry.
Wallet Coupons are a dedicated coupon type that **adds balance to a customer's wallet** when
redeemed, rather than discounting their order. They're ideal for promotions, gift codes, and
goodwill credit.
## Creating a wallet coupon
1. Enable the module: in **TeraWallet → Settings**, turn on **Enable Wallet Coupon**.
2. Create a coupon as you normally would, and mark it as a **Wallet Coupon**.
3. Set the **value** that will be credited to the wallet on redemption, and the **currency**.
When a customer redeems the code, the coupon value is credited to their wallet balance instead of
reducing the cart total.
## Restrictions & limits
Each wallet coupon supports the controls you'd expect from WooCommerce coupons:
* **Email / domain restriction** — limit redemption to specific email addresses or whole domains
(wildcard supported, e.g. `*@company.com`).
* **Usage limits** — cap how many times a coupon can be used globally and per individual user.
* **Expiry date** — set a hard deadline after which the code can no longer be redeemed.
* **Per-coupon currency** — define the currency the value is credited in.
## Bulk generation
A built-in **bulk generator** creates many unique coupon codes at once (for gift-card campaigns or
mass distribution). It's backed by the coupon REST API under `terawallet/v1/coupons`, which also
supports full CRUD and code generation for programmatic workflows — see [Pro Hooks](/pro/hooks).
Combine an email-domain restriction with a usage limit of 1-per-user to hand out one-time welcome
credit to everyone at a partner company.
# Credit Expiry & FIFO
Source: https://docs.standalonetech.com/pro/wallet-expiry
Automatically expire TeraWallet store credit on a schedule, spend the soonest-to-expire credit first, and send reminder and lapse emails.
The Credit Expiry module gives store credit a lifecycle. Credits expire after a configurable
duration, the soonest-to-expire credit is always spent first (FIFO), and expired credit is removed
from both the spendable and the displayed balance.
## How it works
* **Expiry date per credit** — when credit is added, an expiry date is stamped on the ledger row
based on your rules.
* **FIFO redemption** — debits consume credits in **expiry-date order** (oldest/soonest-to-expire
first), so customers always use credit that is about to lapse before newer credit.
* **Currency-aware** — a debit in one currency only consumes credits in that same currency.
* **Balance filtering** — expired credit is excluded from the customer's viewable and spendable
balance (the module hooks the core `woo_wallet_current_balance` filter).
On activation, Pro adds `expire_date` and `amount_redeemed` columns to the core wallet ledger and
runs a one-time background backfill so FIFO is consistent with your existing transaction history.
## Configuration
Go to **TeraWallet → Settings** and open the **Credit Expiry** options:
* **Enable Credit Expiry** — master switch.
* **Credit Expire (default)** — the global duration after which new credit expires (e.g. 30 days).
* **Per-category durations** *(since Pro 1.0.4)* — override the global default for specific
transaction categories (for example, expire cashback faster than top-ups).
Per-transaction expiry can also be set when [importing balances](/importer) (the optional
`expire_date` CSV column) and on admin-side credits.
## Retention emails
Two automated emails keep customers informed:
* **Expiry reminder** — sent before credit is due to expire, nudging the customer to spend it.
* **Expiry notice** — sent when credit has lapsed.
A daily background task (Action Scheduler) processes expirations and reminder windows in paginated
batches, so it scales without loading every credit into memory.
Pair expiry with refunds: instead of refunding cash, issue store credit that expires in, say, 90
days to encourage a repeat purchase.
# Wallet Withdrawal
Source: https://docs.standalonetech.com/pro/withdrawal
Let customers cash out their TeraWallet balance to PayPal, Stripe, Razorpay, Paystack, Cashfree or bank transfer, with admin approval and per-gateway fees.
The Withdrawal module turns store credit into real-world payouts. Customers request a withdrawal
from their account, and you approve or reject it — manually or automatically — paid out through one
of six gateways.
## Supported payout gateways
| Gateway | Notes |
| ------------------------ | ----------------------------------------------------------------------------------- |
| **PayPal** | Payouts API. Loads for any store currency. |
| **Stripe** | Stripe Transfers. Loads for any currency. Supports asynchronous webhook updates. |
| **BACS** (Bank Transfer) | Manual bank transfer; you mark requests paid after sending. Loads for any currency. |
| **Razorpay** (RazorpayX) | `INR` only. |
| **Cashfree** | Payouts v2 API. `INR` only. |
| **Paystack** | `NGN`, `GHS`, `ZAR`, `KES`, `USD`, `EUR`, `GBP`. |
Currency-incompatible gateways are hidden automatically. Developers can register custom gateways via
the `woo_wallet_withdrawal_payment_gateways` filter — see [Pro Hooks](/pro/hooks).
## Admin setup
Go to **TeraWallet → Settings → Withdrawal** and configure:
* **Enable Withdrawal** — master switch for the module.
* **Approval Mode** — approve requests manually, or auto-approve and pay out immediately.
* **Minimum / Maximum Withdrawal** — bounds for a single request.
* **Enable logging** — write per-gateway debug logs (surfaced on each withdrawal screen).
* **Per-gateway options** — enable each gateway, enter its API credentials, and set its processing
fee (see below).
### Processing fees (per gateway)
Each gateway has its own fee, configured with **Enable Processing Fee**, **Fee Type** and **Fee
Amount**:
* **Fee Type**: `percent`, `fixed`, or `percent + fixed` (a percentage plus a flat **Fixed
Component**).
* The fee is **deducted from the payout**, not added to the debit: the wallet is debited the
**requested** amount, and the gateway pays out `amount − fee`.
Fees are configured strictly per gateway. The old global "gateway charge" options were removed in
Pro 1.0.4 in favor of this per-gateway model.
## Customer experience
1. The customer opens **My Account → Wallet** and goes to the **Withdrawal** tab.
2. First time only: they save a **Payment Settings** profile (e.g. PayPal email, bank details)
for their chosen gateway.
3. They enter an amount (within your min/max and their available balance) and submit the request.
4. They receive a **request submitted** email, and **approval** or **rejection** emails as the
request progresses.
A request moves through **pending → approved (paid)** or **rejected**. On approval the wallet is
debited and the payout is sent; idempotency keys ensure re-approving a request can never pay twice.
## Managing requests
Withdrawal requests are stored as their own admin list. For each request you can:
* **Approve** or **Reject** it (rejection returns nothing from the wallet, since the debit happens on
approval).
* Add **notes** — private (staff-only) or customer-visible, like WooCommerce order notes.
* Review **per-withdrawal gateway logs** when logging is enabled.
### Asynchronous payout webhooks
Stripe, PayPal, Razorpay, Cashfree and Paystack can report final payout status back via signed
webhooks under the `terawallet/v1` REST namespace (Stripe's endpoint is
`/wp-json/terawallet/v1/stripe/webhook`). Signatures are verified and replays are rejected. Set the
gateway's webhook secret in its settings to enable this.
Use **BACS** for manual bank transfers where you pay out by hand and simply mark the request
approved once the transfer is sent.
# Release Notes
Source: https://docs.standalonetech.com/releases/changelog
What's new in TeraWallet — a release-by-release summary of features, improvements, fixes and security hardening.
A user-friendly summary of recent TeraWallet releases. For the complete, verbatim developer
changelog, see `changelog.txt` in the plugin package.
**New**
* **Dashboard summary cards.** The customer wallet dashboard now shows a row of cards above the
transaction list — **Total top-ups**, **Total spent** (full wallet payments *and* partial
payments), **Cashback earned** (only when the cashback program is enabled) and **Available
balance**. Add-ons can register their own cards (e.g. "Total withdrawn") via the new
`woo_wallet_dashboard_stat_cards` filter.
* **Partial payment tax treatment.** A new setting lets you choose **Wallet pays goods only**
(default) or **Wallet pays the whole order including tax**, resolving long-standing reports of
tax staying on the full order. See [Partial & Combined Payments](/user-guide/partial-payments).
* **Proportional partial refunds.** Partial wallet payments are now refunded proportionally when
you issue a *partial* WooCommerce refund (previously only full cancellations refunded the
wallet). Opt out per store, or override the amount with `woo_wallet_partial_payment_refund_amount`.
* **"Deduct wallet balance" timing.** Choose to deduct at order placement (default) or **when
payment completes**, so abandoned or failed orders never leave the wallet debited.
* **Better wallet emails.** Both wallet emails support WooCommerce's **Additional content** box,
are grouped under **Payments** in WooCommerce 10.3+, and now include action buttons ("View your
wallet" / "Recharge your wallet now").
**Improvements**
* Partial-payment refunds reverse the exact base-currency amount originally debited — no more
phantom FX gain/loss on multi-currency stores.
* The partial-payment debit is serialized by a per-order lock so concurrent gateway webhooks can't
double-debit.
* The transaction table's **Details** column now wraps instead of truncating, staying readable on
mobile.
**Fixes**
* Closed a silent over-cap where the displayed wallet amount and the actual debit could disagree.
* Fixed the plain-text transaction email showing the balance instead of the transacted amount.
* The low-balance email now fires once when the threshold is crossed, instead of on every debit.
* Corrected a typo in the low-balance email.
* Single-currency stores: a one-time upgrade normalizes leftover non-base ledger rows so the
spendable balance and the displayed balance always agree.
**Security**
* The My Account `wallet_action` parameter is now sanitized and allow-listed before dispatch
(filterable via `woo_wallet_allowed_dashboard_actions`).
* **Transaction category** is now a first-class, indexed column for cheap admin filters and
aggregations.
* New **Transaction descriptions** settings tab with per-category templates and tokens
(`{order_id}`, `{amount}`, `{user_name}`, `{currency}`, `{original_details}`).
* A filterable PHP registry of canonical categories so add-ons can register their own kinds.
* CSV export now includes the `category` column.
* Hardening: category templates are HTML-stripped (no stored XSS), and unknown category slugs
collapse to `other`.
* **Referrals** activity now lives in a dedicated `woo_wallet_referrals` table with a full audit
trail, a customer referral history view, and a new admin **Referral Report** (filters, summary,
CSV export).
* Signup and referral bonuses are now credited for users created via SSO/SAML, social login, the
REST API, WP-CLI and programmatic `wp_insert_user()`.
* Referral bonuses are credited in the store base currency; the "Minimum Order Amount" setting was
clarified to **Minimum Spend**.
* Concurrency and idempotency hardening across bulk admin credit/debit and signup capture.
* New **cashback cap scope** setting: apply the cap **per order** or **per item**.
* New **cashback clawback on refund** (off by default) with an allow-negative option and override
filters.
* A **cashback expiry seam** (`woo_wallet_cashback_expiry_timestamp`) for Pro/add-ons.
* REST transactions expose a typed `category` field and accept a `category=` filter.
* The **Delete Logs** admin action now opens a modal to choose delete mode (soft/hard) and balance
handling (keep/wipe).
* The React **Actions** tab was unified with the standard settings flow.
* A brand-new **React settings interface** with a typed field registry and REST-backed save/load.
* First-class **multi-currency** support with adapters for WOOCS/FOX, WPML/WCML, CURCY, Aelia and
YayCurrency, plus a generic fallback — with per-row currency audit columns for accurate
historical reporting.
# Partial & Combined Payments
Source: https://docs.standalonetech.com/user-guide/partial-payments
How to use wallet balance along with other payment methods at checkout.
Partial payment is a powerful feature that allows customers to use their existing wallet balance to pay for part of an order, while paying the remainder with another gateway (e.g., Stripe, PayPal, or Bank Transfer).
### How It Works
When partial payment is enabled, TeraWallet calculates the available balance and applies it as a **negative fee** to the WooCommerce cart. This effectively reduces the "Total" that needs to be collected by other payment methods.
### Checkout Flow Example
Here is a step-by-step example of how a partial payment transaction works:
1. **User Balance**: The customer has **\$100** in their wallet.
2. **Cart Total**: The customer adds items worth **\$300** to their cart.
3. **Applying Balance**: On the checkout page, the user chooses to use their wallet balance.
4. **Calculated Totals**:
* Subtotal: \$300
* **Wallet Deduction (Via Wallet): -\$100**
* **New Total to Pay: \$200**
5. **Final Payment**: The customer pays the remaining **\$200** using their preferred gateway (e.g., Credit Card).
6. **Post-Payment**:
* WooCommerce marks the order as paid.
* TeraWallet debits \$100 from the customer's wallet ledger.
* The ledger entry will show: "For order payment #1234 (Partial)".
### Auto-Deduct Feature
Administrators can enable **Auto-Deduct** in the settings. When active:
* The maximum available wallet balance is **automatically applied** as a discount when the customer reaches the checkout page.
* The customer doesn't need to manually toggle the option.
### Tax Treatment
**New in 1.6.4.** Set this under **TeraWallet → Settings → General → Partial Payment**.
Because WooCommerce clamps negative fees to the *ex-tax* subtotal, a non-taxable wallet fee can't
pay the tax portion of an order. The **Tax treatment** setting lets you decide how the wallet fee
interacts with tax:
* **Wallet pays goods only** *(default)* — the wallet fee is clamped to the ex-tax subtotal and tax
is charged on the order. Correct when wallet top-ups are **not** taxed at load.
* **Wallet pays the whole order including tax** — the wallet fee is taxable, so the wallet can cover
the tax line too. Use this only when top-ups **are** taxed when the customer loads them.
### When the Wallet is Debited
**New in 1.6.4.** "Deduct wallet balance" timing, under **Settings → General → Partial Payment**.
* **At order placement** *(default)* — the wallet portion is debited immediately when the order is
created.
* **When payment completes** — the wallet is debited only once the order reaches a paid status, so
abandoned or failed orders never leave the wallet debited. If the balance was already spent
elsewhere before payment cleared, the order is placed **on-hold** and the
`woo_wallet_partial_payment_debit_failed` action fires instead of overdrafting the wallet.
### Refund Logic for Partial Payments
If an order paid partially is **cancelled**, the full wallet portion is credited back automatically.
Since 1.6.4, **partial** WooCommerce refunds are also handled: TeraWallet returns a **proportional**
share of the wallet payment to the customer's balance — capped so the cumulative refund can never
exceed the original wallet debit, and idempotent per refund.
* Refunds reverse the exact base-currency amount originally debited, so multi-currency stores see no
phantom FX gain or loss.
* You can opt out per store with **Refund wallet on partial refunds**, or override the amount with
the `woo_wallet_partial_payment_refund_amount` filter.
* The remaining amount (paid via the secondary gateway) must still be refunded separately by the
administrator within that gateway's interface.
### Important Notes
* **Insufficient Balance**: If the wallet balance is zero, the partial payment option will not appear.
* **Full Payment**: If the wallet balance is *greater than or equal to* the order total, the user can pay for the entire order using the **Wallet Gateway** directly, and no other payment method is required.
* **Top-up Conflict**: Partial payments **cannot be used** if the customer is currently attempting to buy a "Wallet Topup" product.
Partial payments are implemented as a non-taxable negative fee in WooCommerce, ensuring that tax calculations on the remaining items are not affected.
# Customer Wallet Dashboard
Source: https://docs.standalonetech.com/user-guide/wallet-dashboard
How customers can manage their balance, view history, and perform transfers.
Customers can manage their wallet balance directly from their WooCommerce account page. TeraWallet seamlessly integrates a "My Wallet" tab into the customer dashboard.
### Dashboard Summary Cards
**New in 1.6.4.** A row of summary cards appears above the recent transactions list.
When a customer opens **My Account → My Wallet**, they first see four at-a-glance cards:
* **Total top-ups** — everything the customer has added to their wallet.
* **Total spent** — both full wallet payments and partial payments.
* **Cashback earned** — shown only when the cashback reward program is enabled.
* **Available balance** — current spendable funds.
These figures share the same helper used by the admin user report, so the customer dashboard and the
admin screen always agree. Add-ons can register their own cards (for example "Total withdrawn") via
the `woo_wallet_dashboard_stat_cards` filter.
### Viewing Balance & Transactions
Customers can navigate to **My Account** > **My Wallet** to:
* **Check Current Balance**: The total available funds are displayed prominently.
* **View Transaction History**: A detailed table showing every credit and debit, along with dates and descriptions. The **Details** column wraps onto multiple lines so long descriptions stay readable on mobile.
* **Filter History**: Customers can use date range filters to audit their transaction history.
### Adding Funds (Top-up)
If the administrator has enabled top-ups, customers can add funds manually:
1. Go to the **My Wallet** tab.
2. Navigate to the **Top-up** sub-tab.
3. Enter the amount you wish to add.
4. Click **Add Balance**.
5. You will be redirected to the WooCommerce checkout page.
6. Complete the payment using any available gateway (e.g., Credit Card, PayPal).
7. Once the payment is processed, the funds are instantly credited to your wallet.
### Sending Funds (Transfer)
Customers can send funds to other registered users if transfers are enabled:
1. Navigate to the **Transfer** sub-tab within **My Wallet**.
2. Enter the recipient's **email address** (the email must be associated with a registered account on the site).
3. Specify the **amount** you want to send.
4. Add an optional **note** for the recipient.
5. Click **Transfer Now**.
6. The amount is instantly debited from your wallet and credited to the recipient's ledger.
### Shortcodes
You can display wallet information anywhere on your site using these shortcodes:
* `[woo-wallet]`: Displays the full wallet dashboard (recommended for a dedicated "My Wallet" page).
* `[mini-wallet]`: Shows a simple widget with the user's current balance, ideal for headers or sidebars.
* `[tw-sell-content]`: Renders the Sell Content action UI (when the Sell Content earning action is enabled).
If you're using a page builder like Elementor or Gutenberg, you can insert the `[mini-wallet]` shortcode into your navigation menu for a personalized user experience.