> ## Documentation Index
> Fetch the complete documentation index at: https://docs.standalonetech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks Reference (Actions & Filters)

> 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 );
```

<Tip>
  When using hooks that modify balance or payment eligibility, always test with a non-admin user to ensure correct front-end behavior.
</Tip>