Audit Log

The WalletPro audit log records every balance-affecting event in a tamper-evident, HMAC-chained ledger so merchants can trace any wallet transaction back to its origin, detect unauthorized changes, and satisfy compliance or accounting requirements.

Overview

Every operation that modifies a wallet balance, credits, debits, top-ups, refunds, cashback awards, milestone payouts, redemption code applications, admin manual adjustments, and expirations, produces an immutable audit entry. Entries are stored in a dedicated database table (wp_walletpro_audit_log) and linked together with an HMAC chain: each row's hash depends on the hash of the previous row, so any retroactive edit to a record breaks the chain and is detectable.

The audit log is separate from WooCommerce order meta and the standard WordPress activity log. It is the authoritative source of truth for wallet liability reporting and GL reconciliation.

What Gets Recorded

The following event types produce audit entries:

How the HMAC Chain Works

When a new audit entry is written, WalletPro computes an HMAC-SHA256 digest over the following fields of that entry:

• Entry ID
• User ID
• Event type
• Amount (in minor currency units)
• Balance after the event
• Timestamp (Unix epoch)
• The hash of the immediately preceding entry for the same wallet

The key material is derived from the site's AUTH_KEY and SECURE_AUTH_KEY constants defined in wp-config.php, combined with a plugin-specific salt. This means the chain integrity is tied to the WordPress installation, not stored in the database.

Viewing the Audit Log

Full Log (All Wallets)

1. In your WordPress admin, navigate to WooCommerce > WalletPro > Audit Log.
2. The table displays all entries across all wallets, sorted by timestamp descending by default.
3. Use the filter bar at the top to narrow results:
   • User, type a customer name or email to filter to one wallet
   • Event Type, select one or more event type codes from the dropdown
   • Date Range, pick a start and end date; defaults to the last 30 days
   • Direction, filter to Credits, Debits, or Meta events only
   • Order ID, filter entries linked to a specific WooCommerce order
   • Admin User, filter entries where an admin performed the action
4. Click Apply Filters. The filtered count appears above the table.

Per-Customer Log

1. Navigate to WooCommerce > Customers and open any customer record.
2. Click the WalletPro tab.
3. The Audit History panel shows the last 50 entries for that customer's wallet, with a link to view the full filtered log.

Audit Entry Details

Click the View link on any row to open the entry detail panel. The panel displays:

Chain Integrity Verification

WalletPro can scan the entire audit log and verify every hash in the chain without modifying any data.

From the Admin UI

1. Navigate to WooCommerce > WalletPro > Audit Log.
2. Click Verify Chain Integrity in the top-right toolbar.
3. A background job runs and reports:
   • Total entries scanned
   • Number of valid entries
   • Number of broken entries, with a link to filter the table to only broken rows
4. Results are saved as a timestamped verification report under WooCommerce > WalletPro > Audit Log > Verification Reports.

Via WP-CLI

# Verify the full chain and output a summary
wp wallet audit verify

# Verify chain for a single user (by user ID or email)
wp wallet audit verify --user=customer@example.com

# Output broken entries as JSON for scripting
wp wallet audit verify --format=json --status=broken

# Run as part of wp wallet doctor (includes chain check)
wp wallet doctor

The wp wallet audit verify command exits with code 0 if all entries are valid, or 1 if any broken entries are found, making it suitable for scheduled monitoring scripts.

Exporting the Audit Log

Manual CSV Export

1. Apply any filters you need (user, date range, event type, etc.).
2. Click Export CSV. The export respects the active filters, so you can export a single customer's history or a specific date range.
3. The downloaded file includes all columns visible in the detail panel, plus the entry_hash and chain_status columns for each row.
4. The filename format is walletpro-audit-YYYY-MM-DD-HHmm.csv.

Scheduled CSV Email

1. Navigate to WooCommerce > WalletPro > Settings > Reports.
2. Under Scheduled Audit Log Export, configure:
   • Enable Scheduled Export, checkbox to turn the schedule on or off
   • Frequency, Daily, Weekly (select day), or Monthly (select day of month)
   • Recipient Email Addresses, comma-separated list; defaults to the admin email
   • Include Event Types, optionally restrict the scheduled export to specific event codes
   • Export Period, Last 24 hours, Last 7 days, or Last 30 days; matched to the frequency setting by default
3. Click Save Changes. The first export runs at the next scheduled window.

Via WP-CLI

# Export all entries from the last 7 days to a file
wp wallet audit export --days=7 --output=/tmp/audit-week.csv

# Export entries for a specific user
wp wallet audit export --user=42 --output=/tmp/user-42-audit.csv

# Export only debit events, output JSON
wp wallet audit export --direction=debit --format=json

# Export a date range
wp wallet audit export \
  --after="2026-01-01" \
  --before="2026-03-31" \
  --output=/tmp/q1-audit.csv

Settings Reference

Audit log settings are found at WooCommerce > WalletPro > Settings > Audit Log.

REST API Access

The audit log is accessible via the WalletPro REST API for programmatic retrieval and integration with external compliance or BI systems.

List Audit Entries

GET /wp-json/walletpro/v1/audit

Query Parameters

Example Response

{
  "total": 1482,
  "pages": 75,
  "entries": [
    {
      "id": 4821,
      "user_id": 107,
      "event_type": "debit_purchase",
      "direction": "debit",
      "amount": "15.00",
      "currency": "USD",
      "balance_before": "42.50",
      "balance_after": "27.50",
      "related_object_type": "order",
      "related_object_id": 9031,
      "performed_by_user_id": 107,
      "performed_by_role": "customer",
      "reason": null,
      "ip_address": "203.0.113.42",
      "created_at": "2026-06-20T14:33:07Z",
      "entry_hash": "a3f9b2c...",
      "chain_status": "valid"
    }
  ]
}

Get Single Entry

GET /wp-json/walletpro/v1/audit/{id}

Returns the full detail object for a single audit entry, including the entry_hash and chain_status fields.

Trigger Chain Verification

POST /wp-json/walletpro/v1/audit/verify

Enqueues a background chain verification job. Returns a job ID that can be polled via GET /wp-json/walletpro/v1/jobs/{job_id}.

Developer Hooks

You can extend audit log behavior using the following hooks.

Actions

/**
 * Fires after an audit entry is written.
 *
 * @param int   $entry_id   The new entry's ID.
 * @param array $entry_data The full entry data array.
 */
do_action( 'walletpro_audit_entry_created', $entry_id, $entry_data );

/**
 * Fires after a chain verification completes.
 *
 * @param int   $scanned  Total entries scanned.
 * @param int   $broken   Number of broken entries found.
 * @param array $broken_ids  Array of broken entry IDs.
 */
do_action( 'walletpro_audit_chain_verified', $scanned, $broken, $broken_ids );

Filters

/**
 * Filter the data written to an audit entry before it is saved.
 * Use to append custom meta fields to the entry's JSON blob.
 *
 * @param array  $entry_data  Entry data about to be persisted.
 * @param string $event_type  The event type code.
 * @param int    $user_id     The wallet owner's user ID.
 * @return array Modified entry data.
 */
add_filter( 'walletpro_audit_entry_data', function( $entry_data, $event_type, $user_id ) {
    if ( $event_type === 'credit_admin_manual' ) {
        $entry_data['meta']['ticket_id'] = get_user_meta( $user_id, '_support_ticket_id', true );
    }
    return $entry_data;
}, 10, 3 );

/**
 * Filter the columns included in a CSV export.
 *
 * @param array $columns  Associative array of column_key => Column Label.
 * @return array Modified columns array.
 */
add_filter( 'walletpro_audit_export_columns', function( $columns ) {
    $columns['meta.ticket_id'] = 'Support Ticket';
    return $columns;
} );

Retention and Pruning

By default, audit entries are kept indefinitely. If you configure a retention period, WalletPro runs a daily background job (via WordPress cron) that permanently deletes entries older than the threshold. The deletion itself is recorded as a audit_prune meta event containing the count and date range of removed entries.

To delete entries manually before the scheduled prune runs:

# Prune entries older than 90 days (dry run, shows count only)
wp wallet audit prune --days=90 --dry-run

# Execute the prune
wp wallet audit prune --days=90