Developer hooks

Refinery Fraud Guard provides actions and filters that allow developers to extend fraud detection, customize rule behavior, integrate with external services, and react to fraud events. Use these hooks in a custom plugin or in your theme’s functions.php.

Actions

refinery_fraud_guard_order_flagged

Fires when an order is flagged by one or more fraud rules. Use this to trigger notifications, log to external services, or take additional action on suspicious orders.

do_action( 'refinery_fraud_guard_order_flagged', int $order_id, array $rules_triggered, string $action )

Parameters:

• $order_id (int) — The WooCommerce order ID.
• $rules_triggered (array) — Array of rule keys that triggered. Possible values: 'geo_mismatch', 'min_amount', 'velocity', 'suspicious_email', 'proxy_vpn'.
• $action (string) — The action taken on the order: 'flag', 'hold', 'cancel', or 'block'.

Example:

add_action( 'refinery_fraud_guard_order_flagged', function( $order_id, $rules, $action ) {
    // Send a Slack notification when an order is flagged.
    wp_remote_post( 'https://hooks.slack.com/services/...', array(
        'body' => wp_json_encode( array(
            'text' => sprintf( 'Order #%d flagged (%s). Rules: %s', $order_id, $action, implode( ', ', $rules ) ),
        ) ),
        'headers' => array( 'Content-Type' => 'application/json' ),
    ) );
}, 10, 3 );

refinery_fraud_guard_order_passed

Fires when an order passes all fraud checks. Use this for logging or analytics on clean orders.

do_action( 'refinery_fraud_guard_order_passed', int $order_id )

Parameters:

• $order_id (int) — The WooCommerce order ID.

refinery_fraud_guard_send_summary

Scheduled action that fires daily (via Action Scheduler) to trigger the fraud summary email. The email includes counts and stats for the previous day.

do_action( 'refinery_fraud_guard_send_summary' )

This action is automatically scheduled when the plugin is active. To change the frequency, unschedule the existing action and register a new one with a different interval.

refinery_fraud_guard_cleanup_blocklist

Scheduled action that fires daily (via Action Scheduler) to remove expired blocklist entries. Entries with an expires_at date in the past are deleted automatically.

do_action( 'refinery_fraud_guard_cleanup_blocklist' )

Filters

refinery_fraud_guard_skip_order

Short-circuit the entire fraud check for a specific order. Return true to skip all fraud rules for the given order.

apply_filters( 'refinery_fraud_guard_skip_order', bool $skip, int $order_id )

Parameters:

• $skip (bool) — Whether to skip the fraud check. Default false.
• $order_id (int) — The WooCommerce order ID.

Example:

// Skip fraud checks for orders placed by administrators.
add_filter( 'refinery_fraud_guard_skip_order', function( $skip, $order_id ) {
    $order = wc_get_order( $order_id );
    $user  = $order->get_user();
    if ( $user && user_can( $user, 'manage_options' ) ) {
        return true;
    }
    return $skip;
}, 10, 2 );

refinery_fraud_guard_check_results

Filter the results of all fraud rule checks before the final action is determined. Use this to add custom fraud rules or override the result of built-in rules.

apply_filters( 'refinery_fraud_guard_check_results', array $results, int $order_id, WC_Order $order )

Parameters:

• $results (array) — Associative array of rule results. Each key is a rule name and each value is an array containing 'passed' (bool), 'action' (string), and rule-specific data.
• $order_id (int) — The WooCommerce order ID.
• $order (WC_Order) — The WooCommerce order object.

Example:

// Add a custom fraud rule that flags orders from a specific country.
add_filter( 'refinery_fraud_guard_check_results', function( $results, $order_id, $order ) {
    $blocked_countries = array( 'XX', 'YY' );
    $billing_country   = $order->get_billing_country();

    $results['blocked_country'] = array(
        'passed' => ! in_array( $billing_country, $blocked_countries, true ),
        'action' => 'hold',
        'country' => $billing_country,
    );

    return $results;
}, 10, 3 );

refinery_fraud_guard_min_amount

Filter the minimum order amount threshold. Orders below this amount are flagged by the minimum amount rule.

apply_filters( 'refinery_fraud_guard_min_amount', float $threshold, WC_Order $order )

Parameters:

• $threshold (float) — The minimum order amount from settings (default: 15).
• $order (WC_Order) — The WooCommerce order object.

Example:

// Set a higher minimum for orders using a specific payment method.
add_filter( 'refinery_fraud_guard_min_amount', function( $threshold, $order ) {
    if ( 'stripe' === $order->get_payment_method() ) {
        return 25.00;
    }
    return $threshold;
}, 10, 2 );

refinery_fraud_guard_ip_geolocation

Filter the IP geolocation result before it is used for the geo mismatch check. Use this to provide a custom geolocation source or override the detected country.

apply_filters( 'refinery_fraud_guard_ip_geolocation', array $data, string $ip_address )

Parameters:

• $data (array) — Geolocation data with keys 'country' (ISO 3166-1 alpha-2 code) and 'region' (state/province).
• $ip_address (string) — The IP address being looked up.

refinery_fraud_guard_disposable_domains

Filter the list of disposable email domains used by the suspicious email rule. Add or remove domains from the built-in blocklist.

apply_filters( 'refinery_fraud_guard_disposable_domains', array $domains )

Parameters:

• $domains (array) — Array of domain strings (e.g., 'mailinator.com', 'guerrillamail.com').

Example:

// Add a custom disposable domain to the blocklist.
add_filter( 'refinery_fraud_guard_disposable_domains', function( $domains ) {
    $domains[] = 'fakeinbox.com';
    return $domains;
} );