Docs/Customer Features/Paying from Balance

Paying from Balance

WalletPro lets customers apply their wallet balance toward any WooCommerce order, covering the full amount, a partial amount alongside another payment method, or anything in between. This reduces checkout friction for returning customers and eliminates gateway fees on repeat purchases.

Customer Feature Checkout Partial Payment Blocks Compatible HPOS Compatible

Overview

When a customer has a wallet balance, a payment option appears at checkout that lets them apply that balance to the current order. The balance application works in two modes:

The debit from the wallet and the gateway charge (if any) happen atomically: if the gateway charge fails, the wallet debit is rolled back. Customers never lose balance due to a failed payment.

ℹ️

Partial payment requires the customer's selected payment gateway to support split-amount charges. Standard gateways (Stripe, PayPal, Square) handle this natively. Custom gateways may need to be tested.

How It Works

At checkout, WalletPro injects a wallet payment section above or alongside the standard payment methods panel. The section displays:

When the customer places the order:

  1. WalletPro places a hold on the wallet balance for the applied amount.
  2. If a secondary gateway is needed, it is charged for the remainder.
  3. On successful gateway response (or immediately if wallet-only), the held balance is permanently debited.
  4. If the gateway fails, the hold is released and the wallet balance is fully restored.
  5. A ledger entry is written with the order ID, applied amount, and timestamp.

Configuration

Navigate to WooCommerce > WalletPro > Settings > Checkout to find the following options:

Setting Default Description
Enable balance at checkout Enabled Master switch. When disabled, the wallet payment section does not appear at checkout even if the customer has a balance.
Allow partial payment Enabled Lets customers apply only part of their balance and pay the remainder with a gateway. When disabled, the wallet either covers the full order or is not used.
Allow custom amount entry Disabled Shows a numeric input so customers can type an exact amount to apply. When disabled, the toggle applies either the full balance or the full order total (whichever is less).
Minimum wallet balance to display option $0.01 Hides the wallet section if the customer's available balance is below this threshold. Useful to avoid showing a near-zero balance that cannot meaningfully offset an order.
Apply balance automatically Disabled Pre-checks the "use my balance" option when the customer loads checkout. The customer can still uncheck it.
Eligible order statuses for debit Processing, Completed The order must reach one of these statuses for the debit to finalize. Useful if you use a custom fulfillment status before marking orders complete.
Excluded product categories (none) Wallet balance cannot be applied to orders containing products from these categories. Useful for gift cards, top-up products, or age-restricted items.
Excluded roles (none) Wallet balance at checkout is unavailable to customers assigned these user roles.
✅

Enable Apply balance automatically together with Allow partial payment to maximize conversion for customers with a balance. The pre-checked toggle and automatic remainder calculation mean fewer steps for customers who almost always use their balance.

Spending Limits and Velocity Caps

Spending controls set under WooCommerce > WalletPro > Settings > Limits apply at checkout and can restrict how much of the wallet balance a customer may use per transaction or per time window:

Setting Where it applies
Maximum wallet spend per order Caps the debit per transaction regardless of balance or order total.
Daily spend cap Cumulative wallet debits across all orders in a rolling 24-hour window.
Weekly spend cap Cumulative wallet debits across a rolling 7-day window.

When a limit would be exceeded, the checkout wallet section shows an inline message explaining the maximum the customer can apply for this order. The customer can still complete the order by paying the difference with a gateway.

Merchant Setup: Step-by-Step

  1. Go to WooCommerce > WalletPro > Settings > Checkout.
  2. Confirm Enable balance at checkout is checked.
  3. Decide whether partial payment is appropriate for your store. If you sell digital products where partial payment creates refund complexity, consider disabling it.
  4. If you want to restrict wallet use on specific product categories (for example, wallet top-up products), add those categories under Excluded product categories. This prevents customers from using wallet credit to buy more wallet credit.
  5. Set Minimum wallet balance to display option to a sensible floor, typically your store's lowest product price, so that the wallet option only appears when it can meaningfully contribute.
  6. Save changes. The wallet payment section appears immediately on the checkout page for logged-in customers with a qualifying balance.
⚠️

Always add your wallet top-up products to Excluded product categories. Without this exclusion, customers could use wallet credit to purchase wallet credit, creating circular liability that distorts your breakage reports.

Customer Experience: Step-by-Step

  1. The customer adds items to the cart and proceeds to checkout.
  2. In the payment section, a WalletPro Balance row appears showing their current balance (for example, "Your balance: $24.50").
  3. The customer checks Apply my balance. The order total updates immediately to reflect the deduction.
  4. If the balance covers the full order total, no secondary payment method is required. The place-order button proceeds with a wallet-only payment.
  5. If the balance is less than the order total (or a partial amount was entered), the customer selects a payment method for the remaining amount and completes checkout normally.
  6. After a successful order, the customer sees the wallet debit reflected in their My Account > Wallet > Statement with the order number and date.

Blocks Checkout

WalletPro registers a Store API extension that makes wallet balance available in the WooCommerce Blocks checkout. The wallet payment UI is injected as a native block payment method, no Classic Checkout shortcode is needed.

In a headless or custom Blocks setup, the applied wallet amount is available on the cart/checkout Store API response under the walletpro extension namespace:

// GET /wc/store/v1/cart
{
  "extensions": {
    "walletpro": {
      "available_balance": "24.50",
      "applied_amount": "12.00",
      "currency": "USD",
      "can_use_at_checkout": true
    }
  }
}

REST API: Apply Balance to an Order

When placing orders programmatically, pass the wallet amount in the order creation request:

# POST /wp-json/walletpro/v1/orders/{order_id}/apply-balance
curl -X POST \
  https://yourstore.com/wp-json/walletpro/v1/orders/1042/apply-balance \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"amount": "12.00"}'

Request parameters:

Parameter Type Required Description
amount string (decimal) Required Amount to debit from the customer's wallet, in the store's base currency. Must not exceed available balance or per-order cap.

Response (200 OK):

{
  "order_id": 1042,
  "applied_amount": "12.00",
  "new_balance": "12.50",
  "ledger_entry_id": 588
}

Developer Hooks

The following filters let you customize balance application behavior without modifying plugin files:

Hook Type Description
walletpro_can_use_balance_at_checkout filter Return false to hide the wallet payment section for a given customer or cart. Receives bool $can_use, WC_Customer $customer, WC_Cart $cart.
walletpro_max_applicable_balance filter Override the maximum amount that can be applied on this checkout. Receives float $max, WC_Customer $customer, WC_Cart $cart.
walletpro_before_balance_debit action Fires immediately before the wallet debit is committed. Receives int $user_id, float $amount, int $order_id.
walletpro_after_balance_debit action Fires after a successful debit. Receives int $user_id, float $amount, int $order_id, int $ledger_entry_id.
walletpro_balance_debit_rolled_back action Fires when a debit is rolled back due to a gateway failure. Receives int $user_id, float $amount, int $order_id.

Example, prevent wallet use on orders containing a specific product:

add_filter( 'walletpro_can_use_balance_at_checkout', function( $can_use, $customer, $cart ) {
    foreach ( $cart->get_cart() as $item ) {
        if ( $item['product_id'] === 99 ) {
            return false;
        }
    }
    return $can_use;
}, 10, 3 );

Refunds and Reversals

When an order is refunded through WooCommerce:

Refund credits appear on the customer's statement with the original order number and a REFUND transaction type.

Audit and Reporting

Every wallet debit at checkout is recorded in the tamper-evident HMAC-chained ledger. To view debits: