Paying from Balance

WalletPro lets customers apply their wallet credit toward any WooCommerce order. The credit can cover the full amount, or part of it with the remainder paid by another gateway (card, PayPal, and so on). This reduces checkout friction for returning customers and cuts gateway fees on repeat purchases.

Overview

When a logged-in customer has a wallet balance, an Apply my account funds option appears at checkout. The balance can be applied in two ways:

• Full payment. The wallet covers the entire order total. The customer selects the WalletPro Store Credit payment method and the whole order is paid from the balance.
• Partial payment. The wallet covers part of the order; the customer applies their credit and pays the remaining amount with their chosen gateway. Applying credit is what this page describes.

When the customer ticks Apply my account funds, the applicable credit is added to the order as a discount line (a negative fee) labelled Wallet Credit Applied. The order total updates immediately, and the customer pays whatever is left with their normal payment method. The applied amount is the lesser of their available balance and the cart's item subtotal.

The wallet debit and any gateway charge are kept consistent. With full payment through the WalletPro Store Credit method, the debit is atomic: if WooCommerce cannot complete the order after the balance is taken, the debit is rolled back and the customer is told their balance was not charged. With partial payment, the recorded credit is debited from the balance only once the order is paid, idempotently, so a customer can never be debited twice for the same order and never loses balance on a failed checkout.

How It Works

At checkout, WalletPro renders a wallet row in the payment area. The row shows:

• An Apply my account funds checkbox with the customer's available balance in the label (for example, "Apply my account funds ($24.50 available)").
• When the credit is applied, a used / remaining-after-order breakdown (new): for example, "$24.50 applied, $0.00 remaining after this order." The breakdown is announced to assistive technology.

The breakdown is a display figure only. used is the lesser of the balance and the order total; remaining is the balance minus what is used (never negative). It does not move money on its own.

When the credit is applied:

1. WalletPro adds a discount line (a negative fee) to the cart labelled Wallet Credit Applied, equal to the lesser of the balance and the cart item subtotal. The order total recalculates so the customer pays only the remainder.
2. To prevent double-counting, the full-balance WalletPro Store Credit payment method is hidden while a partial application is active. The customer pays the remainder with another gateway.
3. The applied amount is recorded on the order as it is created.
4. Once the order is paid (on payment_complete, or when it reaches Processing or Completed), the recorded amount is debited from the balance and a ledger entry is written referencing the order. The debit is guarded by an order-meta marker, so it runs exactly once even if several of those hooks fire.
5. If the balance was drained between checkout and capture, the marker is cleared and an order note is added so a later status transition can retry rather than silently losing the debit.

For full payment through the WalletPro Store Credit method, the gateway debits the whole order total atomically and writes its debit marker before completing the order. If completion fails, it credits the balance back and notes the rollback on the order.

Configuration

The checkout labels and the auto-apply default live under WooCommerce > WalletPro > Settings > General. Each label has a built-in default; clearing a field restores that default.

The full-balance payment method itself is enabled under WooCommerce > Settings > Payments, where you can also override its title and description directly on the gateway.

Spending Limits and Velocity Caps

Per-period spending limits set under WooCommerce > WalletPro > Settings > General restrict how much wallet credit a customer can spend in a rolling window. They are enforced server-side at the money seam, so they cannot be bypassed at checkout.

When applying credit would push the customer over a cap, the credit is simply not applied on that order, and the full-balance payment method is hidden. The customer can still complete the order by paying with a gateway. The window is derived from the existing ledger, so there is no separate counter to keep in sync.

Merchant Setup: Step-by-Step

1. Go to WooCommerce > Settings > Payments and enable the WalletPro Store Credit payment method so customers can also pay an order in full from their balance.
2. Go to WooCommerce > WalletPro > Settings > General and review the Checkout payment title and Applied-credit summary label. Leave them blank to use the defaults (WalletPro Store Credit and Wallet Credit Applied).
3. Decide whether to keep Auto-apply wallet credit at checkout on. On is the default and gives the lowest-friction experience; turn it off if you prefer customers to opt in on each order.
4. If you want to restrict where credit can be used, set Minimum order to spend, and use Exclude sale items or Exclude coupon orders as needed.
5. If you need to cap spending velocity, enable per-period spending limits and set the period and caps.
6. Save changes. The wallet row appears on checkout for logged-in customers with a qualifying balance, on both the classic and Blocks checkout.

Customer Experience: Step-by-Step

1. The customer adds items to the cart and proceeds to checkout.
2. In the payment area, an Apply my account funds row appears showing the available balance (for example, "Apply my account funds ($24.50 available)"). With auto-apply on, it is already checked.
3. While the credit is applied, a breakdown reads, for example, "$24.50 applied, $0.00 remaining after this order." The order total updates to reflect the discount. The customer can uncheck the option to remove the credit.
4. If the balance covers the order in full, the customer can instead pick the WalletPro Store Credit payment method to pay the whole order from their balance, with no other gateway required.
5. If the credit covers only part of the order, the customer pays the remaining amount with their chosen payment method and completes checkout normally.
6. After a successful order, the wallet debit appears in My Account > Wallet with the order number and date.

Blocks Checkout

WalletPro registers a Store API extension so wallet credit works on the WooCommerce Blocks checkout, not just the classic checkout. The full-balance payment method is registered as a native block payment method, and the apply state, fee, gateway-hiding, and idempotent debit are the same shared code paths the classic checkout uses. The Blocks path differs only in its inputs.

In a headless or custom Blocks setup, the wallet data is exposed on the cart Store API response under the walletpro extension namespace. Amounts are 4-decimal strings:

// GET /wc/store/v1/cart
{
  "extensions": {
    "walletpro": {
      "applying": true,
      "available": "24.5000",
      "applied": "12.0000",
      "used": "12.0000",
      "remaining": "12.5000"
    }
  }
}

Fields: applying is whether credit is currently being applied; available is the balance for the active checkout currency; applied is the credit applicable to the cart (lesser of balance and item subtotal); and used / remaining are the breakdown against the order total. To toggle from a headless client, post an extensionCartUpdate to the walletpro namespace with { "apply": true } or { "apply": false }; WooCommerce recalculates the cart and the same money logic applies.

Store API: Apply Credit Headlessly

There is no dedicated "apply balance" REST endpoint. On the Blocks / headless path the apply state is toggled through the standard WooCommerce Store API cart-extension update callback under the walletpro namespace:

// POST /wc/store/v1/cart/extensions
{
  "namespace": "walletpro",
  "data": { "apply": true }
}

Send "apply": false to remove the credit. WooCommerce recalculates the cart, and the recalculated walletpro extension data (see the Blocks section above) reflects the new applying, used, and remaining values. The applied amount is recorded on the order at checkout through WooCommerce's own order pipeline; there is nothing further to call.

Developer Hooks

The customer-facing checkout strings are filterable, so you can rename them without touching the admin screen or plugin files:

Example, rename the applied-credit line for a specific store:

add_filter( 'walletpro_fee_label', function( $label ) {
    return __( 'Loyalty credit', 'my-store' );
} );

The apply, fee, gateway-hiding, and debit-on-paid behaviour is wired to standard WooCommerce hooks (woocommerce_cart_calculate_fees, woocommerce_available_payment_gateways, woocommerce_checkout_create_order, woocommerce_payment_complete, and the Processing / Completed status transitions), so existing WooCommerce extension points apply.

Refunds and Reversals

Refund handling depends on how the order was paid:

• Order paid in full from the wallet (the WalletPro Store Credit method). When you refund the order in WooCommerce, the refunded amount is credited back to the customer's wallet for the order's currency, and a ledger entry is written referencing the order. The gateway's internal debit marker is reduced by the refund so a later read reflects how much of the original charge is still outstanding.
• Order paid partly with applied credit and the remainder by another gateway. A refund issued to that other gateway returns money to the original payment method; it does not touch the wallet. The applied wallet credit was a discount on the order rather than a gateway charge, so reversing it back to the wallet is a manual decision: use a manual adjustment to credit the wallet for the share you want to return.

Refund credits appear on the customer's statement with a Refund transaction type. Each WooCommerce refund record triggers one wallet credit, so the credit is idempotent at the WooCommerce layer.

Audit and Reporting

Every wallet debit at checkout is recorded in the tamper-evident ledger, and each movement carries the order it relates to. To review activity:

• Per customer: the customer sees their own debits and refunds in My Account > Wallet, with the order number and date. Each partial debit shows as a Payment entry.
• Store-wide balances: WooCommerce > Wallet Balances lists every customer with their current balance and last activity.
• Reports: WooCommerce > Wallet Reports shows issued-versus-redeemed activity, period-over-period deltas, active wallets, and liability share.
• CSV export: the transaction ledger can be exported to CSV, and a periodic ledger CSV can be scheduled and emailed to admins. See the audit log and financial reports for details.