Here is the HTML body content for the "Hooks & Filters" documentation page: ```html

Hooks & Filters

WalletPro exposes over 80 action hooks and filter hooks throughout its codebase, giving developers precise control over wallet behavior, UI output, ledger logic, reward calculations, and integrations without modifying plugin files.

Developer PHP WooCommerce Extensibility Customization

Overview

All WalletPro hooks follow WordPress conventions. Actions use do_action() and filters use apply_filters(). Hook names use the walletpro_ prefix to avoid collisions with WooCommerce core or other plugins.

Hooks are organized into the following functional areas:

Balance & Ledger, debit, credit, balance checks, HMAC chain events
Checkout & Payment, wallet application at checkout, partial payment flow
Rewards, cashback, milestones, referrals, gift credit calculations
Redemption Codes, validation, rate limiting, code application
Transfers & Requests, peer transfers, money requests, withdrawal submissions
Top-Up, gateway selection, amount rules, auto-reload triggers
My Account, dashboard output, statement rendering
Admin, manual credit/debit forms, ledger display, export output
Authentication, step-up auth prompts, KYC gating
Notifications, email and webhook dispatch

ℹ️

All hooks documented here are considered stable public API. Hooks marked @internal in source docblocks are subject to change without notice and should not be used in production extensions.

Balance & Ledger Hooks

Actions

Hook	Arguments	Description
`walletpro_before_credit`	`$user_id, $amount, $currency, $reason`	Fires immediately before a credit is written to the ledger. Throw a `WalletPro_Exception` here to abort the credit.
`walletpro_after_credit`	`$user_id, $amount, $currency, $ledger_entry_id`	Fires after a successful credit. The ledger entry is already committed and HMAC-chained at this point.
`walletpro_before_debit`	`$user_id, $amount, $currency, $order_id`	Fires before an atomic debit. Return value is not used; throw to abort.
`walletpro_after_debit`	`$user_id, $amount, $currency, $order_id, $ledger_entry_id`	Fires after a successful debit and ledger commit.
`walletpro_ledger_chain_broken`	`$user_id, $broken_entry_id, $expected_hash, $actual_hash`	Fires when HMAC chain verification detects tampering. Use to trigger alerts.
`walletpro_balance_adjusted`	`$user_id, $old_balance, $new_balance, $currency`	Fires after any balance change (credit or debit). Useful for sync to external systems.

Filters

Hook	Default	Arguments	Description
`walletpro_credit_amount`	`$amount`	`$amount, $user_id, $reason, $currency`	Filter the amount before it is credited. Return a modified float. Return `0` to suppress.
`walletpro_debit_amount`	`$amount`	`$amount, $user_id, $order_id, $currency`	Filter the debit amount before the atomic debit runs.
`walletpro_ledger_entry_meta`	`[]`	`$meta, $entry_type, $user_id`	Merge additional key/value pairs into a ledger entry's metadata column before insert.
`walletpro_balance_precision`	`2`	`$decimals, $currency`	Control decimal precision for balance storage and display per currency.

Example: Block a debit and log it

// Prevent debits above $500 for guest-converted accounts
add_action( 'walletpro_before_debit', function( $user_id, $amount, $currency, $order_id ) {
    if ( $amount > 500 && get_user_meta( $user_id, '_walletpro_guest_converted', true ) ) {
        error_log( sprintf( 'WalletPro: blocked large debit %s %s for user %d on order %d', $amount, $currency, $user_id, $order_id ) );
        throw new WalletPro_Exception( 'Debit exceeds limit for converted guest accounts.', 'debit_limit_exceeded' );
    }
}, 10, 4 );

Checkout & Payment Hooks

Actions

Hook	Arguments	Description
`walletpro_checkout_wallet_applied`	`$user_id, $applied_amount, $order_total, $remaining`	Fires when the wallet is applied at checkout (partial or full). `$remaining` is the amount still owed via other payment methods.
`walletpro_checkout_wallet_removed`	`$user_id, $session_key`	Fires when the customer deselects wallet payment from the checkout form.
`walletpro_order_wallet_payment_complete`	`$order_id, $user_id, $debited_amount, $currency`	Fires after an order is fully processed and the wallet debit is committed.
`walletpro_order_partial_payment_complete`	`$order_id, $user_id, $wallet_portion, $gateway_portion`	Fires when an order uses split payment (wallet + gateway).

Filters

Hook	Default	Arguments	Description
`walletpro_checkout_wallet_label`	`'Pay with Wallet'`	`$label, $user_id, $balance`	Customize the label shown on the checkout payment method row.
`walletpro_checkout_max_wallet_amount`	`$balance`	`$max, $user_id, $cart_total, $currency`	Cap how much wallet balance can be applied to a single order. Return a float.
`walletpro_checkout_eligible`	`true`	`$eligible, $user_id, $cart`	Return `false` to hide the wallet payment option for specific users or cart states.
`walletpro_partial_payment_enabled`	`true`	`$enabled, $user_id, $cart_total`	Return `false` to require full wallet payment or no wallet payment (no split).
`walletpro_allowed_product_ids`	`[]`	`$ids, $user_id`	Restrict wallet payment to specific product IDs. Return a non-empty array to enforce the allowlist. Empty array means no restriction.

Example: Restrict wallet to orders under $200

add_filter( 'walletpro_checkout_max_wallet_amount', function( $max, $user_id, $cart_total, $currency ) {
    return min( $max, 200.00 );
}, 10, 4 );

Rewards Hooks

Actions

Hook	Arguments	Description
`walletpro_cashback_awarded`	`$user_id, $order_id, $cashback_amount, $currency`	Fires after cashback is credited to the wallet following order completion.
`walletpro_milestone_reached`	`$user_id, $milestone_id, $reward_amount, $currency`	Fires when a customer hits a defined spending or activity milestone.
`walletpro_referral_reward_issued`	`$referrer_id, $referee_id, $reward_amount, $currency`	Fires after a referral reward is credited to the referring customer.
`walletpro_gift_credit_issued`	`$recipient_id, $sender_id, $amount, $currency, $message`	Fires after a gift credit is delivered to the recipient's wallet.

Filters

Hook	Default	Arguments	Description
`walletpro_cashback_rate`	`$rate`	`$rate, $user_id, $order_id, $order_total`	Modify the cashback percentage (0 to 100) before it is applied to an order.
`walletpro_cashback_eligible_amount`	`$order_total`	`$amount, $order_id, $user_id`	Control which portion of the order total earns cashback (e.g., exclude tax or shipping).
`walletpro_milestone_reward_amount`	`$amount`	`$amount, $milestone_id, $user_id`	Override the reward amount for a specific milestone ID at runtime.
`walletpro_referral_reward_amount`	`$amount`	`$amount, $referrer_id, $referee_id`	Adjust the referral reward amount dynamically based on referrer or referee properties.
`walletpro_cashback_excluded_categories`	`[]`	`$category_ids, $order_id`	Return an array of WooCommerce category IDs whose line items are excluded from cashback calculation.

Example: Double cashback for loyalty-tier customers

add_filter( 'walletpro_cashback_rate', function( $rate, $user_id, $order_id, $order_total ) {
    if ( wc_get_customer_order_count( $user_id ) >= 10 ) {
        return $rate * 2;
    }
    return $rate;
}, 10, 4 );

Redemption Code Hooks

Actions

Hook	Arguments	Description
`walletpro_code_redeemed`	`$user_id, $code, $credit_amount, $currency`	Fires after a redemption code is successfully applied and the credit is written.
`walletpro_code_redemption_failed`	`$user_id, $code, $error_code`	Fires when code redemption fails. `$error_code` is one of: `invalid`, `expired`, `exhausted`, `rate_limited`, `already_used`.
`walletpro_code_rate_limit_hit`	`$user_id, $code, $attempts, $window_seconds`	Fires when a user exceeds the redemption attempt rate limit for a code.

Filters

Hook	Default	Arguments	Description
`walletpro_code_credit_amount`	`$amount`	`$amount, $code, $user_id`	Modify the credit amount before it is applied when a code is redeemed.
`walletpro_code_eligible_user`	`true`	`$eligible, $user_id, $code`	Return `false` to block a specific user or role from redeeming a code.
`walletpro_code_rate_limit_window`	`3600`	`$seconds, $code`	Adjust the rate limit window in seconds for code redemption attempts.
`walletpro_code_rate_limit_max_attempts`	`5`	`$max, $code, $user_id`	Adjust the maximum number of failed redemption attempts allowed within the window.

Transfers & Money Requests

Actions

Hook	Arguments	Description
`walletpro_transfer_sent`	`$sender_id, $recipient_id, $amount, $currency, $note`	Fires after a peer-to-peer wallet transfer completes. Both ledger entries are committed.
`walletpro_transfer_failed`	`$sender_id, $recipient_id, $amount, $error_code`	Fires when a transfer fails before the ledger write. Balance is unchanged.
`walletpro_money_request_created`	`$request_id, $requester_id, $target_id, $amount, $currency`	Fires when a money request is submitted.
`walletpro_money_request_fulfilled`	`$request_id, $requester_id, $payer_id, $amount, $currency`	Fires when a money request is approved and the transfer executes.
`walletpro_money_request_declined`	`$request_id, $requester_id, $decliner_id`	Fires when a money request is declined by the target user.
`walletpro_withdrawal_submitted`	`$withdrawal_id, $user_id, $amount, $currency, $method`	Fires when a customer submits a withdrawal request.
`walletpro_withdrawal_approved`	`$withdrawal_id, $user_id, $amount, $currency`	Fires when an admin approves a withdrawal request.

Filters

Hook	Default	Arguments	Description
`walletpro_transfer_eligible`	`true`	`$eligible, $sender_id, $recipient_id, $amount`	Return `false` to block a specific transfer before it processes.
`walletpro_transfer_fee`	`0.00`	`$fee, $sender_id, $recipient_id, $amount, $currency`	Deduct a transfer fee from the sender's balance. Return a float amount.
`walletpro_transfer_max_amount`	`$sender_balance`	`$max, $sender_id, $currency`	Cap the maximum single transfer amount.
`walletpro_withdrawal_min_amount`	`1.00`	`$min, $user_id, $currency`	Set the minimum withdrawal amount per user or currency.

Top-Up & Auto-Reload Hooks

Actions

Hook	Arguments	Description
`walletpro_topup_complete`	`$user_id, $amount, $currency, $order_id, $gateway_id`	Fires after a top-up order is paid and the credit is posted to the wallet.
`walletpro_autoreload_triggered`	`$user_id, $trigger_balance, $reload_amount, $currency`	Fires when a customer's balance drops to the auto-reload threshold and an order is created.
`walletpro_autoreload_failed`	`$user_id, $reload_amount, $currency, $error_message`	Fires when the auto-reload payment attempt fails (e.g., saved card declined).

Filters

Hook	Default	Arguments	Description
`walletpro_topup_amounts`	`[10, 25, 50, 100]`	`$amounts, $user_id, $currency`	Override the preset top-up amount options shown on the top-up form. Return a flat array of numeric values.
`walletpro_topup_min_amount`	`1.00`	`$min, $user_id, $currency`	Set the minimum allowed top-up amount.
`walletpro_topup_max_amount`	`10000.00`	`$max, $user_id, $currency`	Cap the maximum single top-up amount.
`walletpro_autoreload_eligible`	`true`	`$eligible, $user_id`	Return `false` to disable auto-reload for specific users or roles.
`walletpro_topup_product_id`	`$id`	`$product_id, $currency`	Override the internal WooCommerce product used to process top-up payments for a given currency.

My Account & Statement Hooks

Actions

Hook	Arguments	Description
`walletpro_myaccount_dashboard_before`	`$user_id`	Output content before the wallet dashboard panel in My Account.
`walletpro_myaccount_dashboard_after`	`$user_id`	Output content after the wallet dashboard panel in My Account.
`walletpro_statement_before_table`	`$user_id, $filters`	Output content before the statement transaction table.
`walletpro_statement_after_table`	`$user_id, $filters`	Output content after the statement transaction table.

Filters

Hook	Default	Arguments	Description
`walletpro_myaccount_tabs`	`$tabs`	`$tabs, $user_id`	Add, remove, or reorder tabs in the wallet section of My Account. Array of `['slug' => ..., 'label' => ..., 'callback' => ...]`.
`walletpro_statement_columns`	`$columns`	`$columns, $user_id`	Add or remove columns from the printable statement table. Keyed by column slug.
`walletpro_statement_row_data`	`$row`	`$row, $ledger_entry, $user_id`	Modify data in a single statement row before render. Useful for appending custom meta columns.
`walletpro_statement_export_filename`	`'wallet-statement.csv'`	`$filename, $user_id, $date_from, $date_to`	Customize the downloaded CSV filename for the customer statement.

Admin Hooks

Actions

Hook	Arguments	Description
`walletpro_admin_manual_credit`	`$user_id, $amount, $currency, $reason, $admin_id`	Fires after an admin manually credits a wallet from WooCommerce > WalletPro > Customers.
`walletpro_admin_manual_debit`	`$user_id, $amount, $currency, $reason, $admin_id`	Fires after an admin manually debits a wallet.
`walletpro_admin_export_complete`	`$export_type, $admin_id, $file_path`	Fires after an admin CSV export is generated. `$export_type` is one of: `ledger`, `liability`, `breakage`, `gl`.
`walletpro_spending_limit_exceeded`	`$user_id, $attempted_amount, $limit, $period`	Fires when a checkout debit would exceed the configured spending limit.
`walletpro_velocity_cap_hit`	`$user_id, $transaction_count, $cap, $window_seconds`	Fires when a user hits the velocity cap for wallet transactions.

Filters

Hook	Default	Arguments	Description
`walletpro_admin_customers_columns`	`$columns`	`$columns`	Add columns to the admin Customers balance table at WooCommerce > WalletPro > Customers.
`walletpro_admin_customers_column_data`	`''`	`$value, $column_slug, $user_id`	Populate a custom column cell in the admin customers table.
`walletpro_export_gl_row`	`$row`	`$row, $ledger_entry`	Modify a single row in the GL-friendly CSV export before it is written.
`walletpro_liability_report_data`	`$data`	`$data, $date_from, $date_to`	Modify the dataset powering the liability report before it renders or exports.
`walletpro_role_spending_limit`	`$limit`	`$limit, $user_id, $role`	Override the spending limit for a user based on their role at runtime.

Example: Add a "Loyalty Tier" column to the admin customers table

add_filter( 'walletpro_admin_customers_columns', function( $columns ) {
    $columns['loyalty_tier'] = __( 'Loyalty Tier', 'my-plugin' );
    return $columns;
} );

add_filter( 'walletpro_admin_customers_column_data', function( $value, $column, $user_id ) {
    if ( 'loyalty_tier' === $column ) {
        return esc_html( get_user_meta( $user_id, 'loyalty_tier', true ) ?: 'Standard' );
    }
    return $value;
}, 10, 3 );

Authentication & KYC Hooks

Actions

Hook	Arguments	Description
`walletpro_stepup_auth_required`	`$user_id, $action, $amount`	Fires when a step-up authentication challenge is triggered. `$action` is one of: `withdrawal`, `transfer`, `topup`.
`walletpro_stepup_auth_passed`	`$user_id, $action`	Fires when step-up authentication is successfully completed.
`walletpro_stepup_auth_failed`	`$user_id, $action, $attempts`	Fires when step-up authentication fails.
`walletpro_kyc_gate_blocked`	`$user_id, $action, $kyc_status`	Fires when a KYC-gated action is blocked. `$kyc_status` reflects the user's current verification status.

Filters

Hook	Default	Arguments	Description
`walletpro_stepup_threshold`	`$threshold`	`$threshold, $action, $user_id`	Override the currency amount above which step-up auth is required for a given action.
`walletpro_kyc_required_actions`	`['withdrawal', 'transfer']`	`$actions, $user_id`	Control which actions require KYC verification. Return an array of action slugs.
`walletpro_kyc_status`	`$status`	`$status, $user_id`	Override the resolved KYC status for a user. Useful for integrating an external KYC provider. Expected values: `none`, `pending`, `verified`, `rejected`.

Example: Integrate an external KYC provider

add_filter( 'walletpro_kyc_status', function( $status, $user_id ) {
    $external_status = my_kyc_provider_get_status( get_user_meta( $user_id, 'kyc_token', true ) );
    if ( $external_status === 'APPROVED' ) {
        return 'verified';
    }
    if ( $external_status === 'PENDING' ) {
        return 'pending';
    }
    return 'none';
}, 10, 2 );

Notification Hooks

Actions

Hook	Arguments	Description
`walletpro_email_before_send`	`$notification_type, $user_id, $args`	Fires before WalletPro sends a transactional email. Return nothing; throw `WalletPro_Exception` to suppress the send.
`walletpro_email_sent`	`$notification_type, $user_id, $to_address`	Fires after a transactional email is dispatched.
`walletpro_webhook_before_dispatch`	`$event_name, $payload, $endpoint_url`	Fires before a signed outbound webhook is sent.
`walletpro_webhook_dispatched`	`$event_name, $payload, $http_response_code`	Fires after a webhook dispatch attempt, whether successful or not.

Filters

Hook	Default	Arguments	Description
`walletpro_email_subject`	`$subject`	`$subject, $notification_type, $user_id`	Override the subject line for any WalletPro transactional email.
`walletpro_email_args`	`$args`	`$args, $notification_type, $user_id`	Modify the template variables available to a WalletPro email template.
`walletpro_webhook_payload`	`$payload`	`$payload, $event_name`	Modify the payload array before it is JSON-encoded and signed for dispatch.
`walletpro_webhook_headers`	`$headers`	`$headers, $event_name, $endpoint_url`	Add or modify HTTP headers sent with outbound webhook requests.

✅

All WalletPro notification types are listed in WalletPro\Notifications\Types. Common values include credit_received, debit_posted, topup_complete, transfer_sent, transfer_received, withdrawal_approved, code_redeemed, cashback_awarded, and autoreload_failed.

Spending Limits & Velocity Filters

Hook	Default	Arguments	Description
`walletpro_spending_limit_amount`	`$limit`	`$limit, $user_id, $period, $currency`	Override the configured spending limit for a user at runtime. `$period` is `daily`, `weekly`, or `monthly`.
`walletpro_velocity_cap_count`	`$cap`	`$cap, $user_id, $window_seconds`	Override the maximum number of wallet transactions allowed per window.
`walletpro_spending_limit_enabled`	`true`	`$enabled, $user_id`	Return `false` to exempt a user from spending limit enforcement entirely.

Multi-Currency Filters

Hook	Default	Arguments	Description
`walletpro_active_currencies`	`$currencies`	`$currencies, $user_id`	Control which currency wallets are active for a given user. Return an array of ISO 4217 codes.
`walletpro_default_currency`	`get_woocommerce_currency()`	`$currency, $user_id`	Override the default wallet currency for a user. This affects which balance is shown on the checkout page.
`walletpro_exchange_rate`	`1.0`	`$rate, $from_currency, $to_currency`	Provide a live exchange rate for cross-currency operations. WalletPro does not fetch rates automatically; return a float from your exchange rate source.

Example: Supply live exchange rates

add_filter( 'walletpro_exchange_rate', function( $rate, $from, $to ) {
    $rates = wp_cache_get( 'my_fx_rates' );
    if ( false === $rates ) {
        $rates = my_fetch_fx_rates();
        wp_cache_set( 'my_fx_rates', $rates, '', 3600 );
    }
    return isset( $rates[ $from ][ $to ] ) ? (float) $rates[ $from ][ $to ] : $rate;
}, 10, 3 );

Hook Priority & Execution Order

WalletPro registers its own internal callbacks at priority 10. Use priority 5 to run before WalletPro's own logic, or priority 20 or higher to run after it. For filters that modify amounts, run at priority 5 to ensure the modified value is what WalletPro acts on.

⚠️

Never call WalletPro\Ledger::credit() or WalletPro\Ledger::debit() directly inside a walletpro_before_credit or walletpro_before_debit hook, this will cause recursive ledger writes. Use walletpro_after_credit or walletpro_after_debit if you need to issue a follow-on transaction.

Discovering All Registered Hooks

You can enumerate every WalletPro hook registered in the current request using wp wallet doctor --hooks from the WP-CLI command or by searching the plugin source for the walletpro_ prefix:

# List all WalletPro hooks from CLI
wp wallet doctor --hooks

# Search plugin source for hook names
grep -rn "do_action\|apply_filters" wp-content/plugins/walletpro/src/ \
  | grep "walletpro_" \
  | awk -F: '{ print $1, $3 }'

The wp wallet doctor --hooks output includes the hook name, argument count, and the file and line number where it fires, which is the fastest way to confirm hook availability in the installed version.