Withdrawals

Withdrawals let customers convert their wallet balance to an external payment method, such as a bank transfer or PayPal payout. Merchants control which methods are available, minimum amounts, and whether requests require manual approval before funds are released.

Overview

When a customer accumulates wallet balance, through top-ups, cashback rewards, or referral credits, they may want to recover that balance as real money rather than spend it in-store. The Withdrawals feature provides a governed pathway for this: the customer submits a request, the merchant reviews it (or approves it automatically), and the payout is dispatched through the merchant's chosen method.

Withdrawal requests are tracked on a per-customer basis with full status history. Every state change is recorded in the tamper-evident HMAC-chained audit ledger, so balance reductions are always traceable.

How It Works

1. The customer submits a withdrawal request from their My Account wallet dashboard, specifying the amount and preferred payout method.
2. WalletPro immediately deducts the requested amount from the customer's available balance and places it in a Pending hold. The customer cannot spend those funds while a request is pending.
3. If Auto-Approve is enabled and the request meets all configured rules, the status advances to Approved automatically. Otherwise, the merchant reviews the request manually.
4. The merchant completes the external payout (bank transfer, PayPal, etc.) through their payment provider.
5. The merchant marks the request as Completed inside WalletPro. The held balance is permanently deducted and the audit ledger is updated.
6. If the merchant rejects the request, the held balance is returned to the customer's available balance and the customer is notified by email.

Request Statuses

Configuration

Navigate to WooCommerce > WalletPro > Settings > Withdrawals to configure withdrawal behavior.

General Settings

Payout Methods

Go to WooCommerce > WalletPro > Settings > Withdrawals > Payout Methods to define which options appear to customers.

Notifications

Navigate to WooCommerce > WalletPro > Settings > Withdrawals > Notifications.

Merchant: Managing Withdrawal Requests

Viewing the Request Queue

Go to WooCommerce > WalletPro > Withdrawals. The table lists all requests across all customers with columns for: customer name, amount, payout method, submitted date, and current status.

Use the Status filter dropdown and the Date Range picker to narrow the list. You can also search by customer name or email using the search box at the top right.

Approving a Request

1. Click a request row to open the detail panel.
2. Review the customer's payout details (bank account, PayPal email, etc.).
3. Complete the external payout through your payment provider (this happens outside WalletPro).
4. Return to the request detail panel and click Mark as Completed. You may optionally enter a reference number (e.g., a bank transfer ID) in the Payout Reference field, this is stored on the record and visible to the customer.
5. Click Confirm. The balance is permanently deducted and the audit ledger entry is written.

Rejecting a Request

1. Open the request detail panel.
2. Click Reject Request.
3. Enter a reason in the Rejection Note field. This note is included in the customer notification email.
4. Click Confirm Rejection. The held balance is immediately returned to the customer's available wallet balance.

Bulk Actions

From the Withdrawals list, check multiple requests and use the Bulk Actions dropdown to:

• Approve selected, Advance Pending requests to Approved status.
• Mark completed, Mark Approved requests as Completed. Use this after processing a batch of payouts externally.
• Reject selected, Reject all selected Pending or Approved requests. You will be prompted for a shared rejection note.

Exporting Requests

Click Export CSV at the top of the Withdrawals list to download the currently filtered set of requests. The export includes: request ID, customer name, customer email, amount, payout method, payout details, submitted date, completed date, payout reference, and status.

This export is suitable for reconciliation with your bank or PayPal payout records.

Customer: Submitting a Withdrawal Request

Where to Find It

Customers navigate to My Account > Wallet > Withdraw. The tab is only visible when the merchant has enabled withdrawals and the customer has a positive balance.

Submitting a Request

1. On the Withdraw tab, enter the desired withdrawal amount. The available balance and any applicable minimums/maximums are shown below the field.
2. Select a Payout Method from the options the merchant has enabled.
3. Fill in the required payout details for the selected method:
   • Bank Transfer: Account holder name, routing number, account number.
   • PayPal: PayPal email address.
   • Custom method: The free-text field as labeled by the merchant.
4. Click Submit Request.
5. A confirmation message displays the request ID and the merchant's payout instructions. A confirmation email is sent if the merchant has that notification enabled.

Tracking Request Status

The Withdraw tab shows a Request History table below the submission form, listing all the customer's past and current requests with their status and submitted date. Customers can click a request to view its detail, including the payout reference number if one was entered by the merchant.

If Allow Customer Cancellation is enabled by the merchant, a Cancel button appears next to Pending requests. Clicking it immediately returns the held amount to the customer's available balance.

Audit Trail

Every withdrawal state transition is recorded in WalletPro's HMAC-chained audit ledger. Ledger entries include:

• The acting user (customer who submitted, admin who approved/rejected)
• Timestamp
• Previous and new balance values
• Request ID and status transition
• Payout reference (if provided)

You can view the ledger for a specific customer at WooCommerce > WalletPro > Customers > [Customer Name] > Ledger. Withdrawal entries are prefixed with the entry type withdrawal_debit or withdrawal_hold.

Developer Reference

REST API

Full withdrawal endpoints are available under the walletpro/v1 namespace. See the REST API reference for authentication details.

List Withdrawal Requests

// GET /wp-json/walletpro/v1/withdrawals
// Query params: customer_id, status, per_page, page, after, before

fetch('/wp-json/walletpro/v1/withdrawals?status=pending&per_page=20', {
  headers: {
    'Authorization': 'Bearer <token>'
  }
});

Example response:

{
  "requests": [
    {
      "id": 1042,
      "customer_id": 88,
      "amount": "75.00",
      "currency": "USD",
      "status": "pending",
      "payout_method": "bank_transfer",
      "payout_details": {
        "account_holder": "Jane Smith",
        "routing_number": "****6789",
        "account_number": "****4321"
      },
      "payout_reference": null,
      "submitted_at": "2026-06-18T14:23:00Z",
      "updated_at": "2026-06-18T14:23:00Z"
    }
  ],
  "total": 1,
  "pages": 1
}

Update Request Status

// PATCH /wp-json/walletpro/v1/withdrawals/{id}

fetch('/wp-json/walletpro/v1/withdrawals/1042', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "status": "completed",
    "payout_reference": "TXN-20260618-002"
  })
});

Valid status transitions via API:

Hooks and Filters

Use these hooks to extend or modify withdrawal behavior.

walletpro_before_withdrawal_submit

Fires before a withdrawal request is saved. Return a WP_Error to block the submission and surface an error message to the customer.

add_filter( 'walletpro_before_withdrawal_submit', function( $error, $customer_id, $amount, $method ) {
    // Block withdrawals for customers without a verified email
    if ( ! email_exists( get_userdata( $customer_id )->user_email ) ) {
        return new WP_Error( 'unverified_email', 'Please verify your email before requesting a withdrawal.' );
    }
    return $error;
}, 10, 4 );

walletpro_withdrawal_status_changed

Fires after a withdrawal request transitions to a new status.

add_action( 'walletpro_withdrawal_status_changed', function( $request_id, $new_status, $old_status, $customer_id ) {
    if ( $new_status === 'completed' ) {
        // Trigger your own payout reconciliation logic
        my_reconcile_payout( $request_id );
    }
}, 10, 4 );

walletpro_withdrawal_payout_methods

Filter the list of payout methods available to a customer. Return a modified array to add or remove methods dynamically.

add_filter( 'walletpro_withdrawal_payout_methods', function( $methods, $customer_id ) {
    // Only offer bank transfer to wholesale role customers
    if ( ! user_can( $customer_id, 'wholesale_customer' ) ) {
        unset( $methods['bank_transfer'] );
    }
    return $methods;
}, 10, 2 );

WP-CLI

# List all pending withdrawal requests
wp wallet withdrawals list --status=pending

# Approve a specific request
wp wallet withdrawals approve 1042

# Mark a request as completed with a payout reference
wp wallet withdrawals complete 1042 --reference="TXN-20260618-002"

# Reject a request with a reason
wp wallet withdrawals reject 1042 --reason="Unable to verify bank details"

# Export all completed withdrawals from June 2026 to CSV
wp wallet withdrawals export --status=completed --after=2026-06-01 --before=2026-06-30 --format=csv > june-payouts.csv

Webhooks

WalletPro fires signed outbound webhooks for each withdrawal state change. See the Webhooks reference for signature verification details.

Relevant events:

Example withdrawal.completed payload:

{
  "event": "withdrawal.completed",
  "timestamp": "2026-06-20T09:41:00Z",
  "data": {
    "id": 1042,
    "customer_id": 88,
    "amount": "75.00",
    "currency": "USD",
    "payout_method": "bank_transfer",
    "payout_reference": "TXN-20260618-002",
    "completed_at": "2026-06-20T09:41:00Z"
  }
}