README

A focused PHP library for the MaxMind minFraud Score API, built for WordPress with wp_remote_post and transient caching. No external HTTP dependencies. Drop-in for fraud-scoring at checkout, on signup, or anywhere a 0-99 risk score is useful.

Features

• 🎯 One thing well — wraps the minFraud Score endpoint (the cheapest of MaxMind's three minFraud tiers, returns the 0-99 risk score)
• 💰 Funds-aware — surfaces funds_remaining / queries_remaining from every successful response so you can wire up budget alerts
• 🚦 Stable error handling — distinguishes transport / auth / quota failures via WP_Error rather than coercing them into a 0 score
• 🪶 Zero deps — only PHP and WordPress's HTTP API
• 🔁 Transient caching — repeat lookups within a 10-minute window cost zero API calls
• 📦 Predictable response shape — getter-friendly Score wrapper that won't break when MaxMind extends the JSON

Requirements

• PHP 7.4 or later
• WordPress 5.0 or later
• MaxMind account + minFraud license key

Installation

composer require arraypress/maxmind-minfraud

Quick start

use ArrayPress\MaxMind\MinFraud\Client;

$client = new Client( '123456', 'your-license-key' );

$result = $client->check_score( [
    'device' => [ 'ip_address' => '203.0.113.42' ],
    'email'  => [ 'address' => 'alice@example.com' ],
    'billing' => [
        'country' => 'US',
        'region'  => 'CA',
        'city'    => 'Los Angeles',
        'postal'  => '90210',
    ],
] );

if ( is_wp_error( $result ) ) {
    error_log( 'minFraud failed: ' . $result->get_error_message() );
    return;
}

if ( $result->is_high_risk() ) {
    // 75+ risk score — block / hold the order
}

$score    = $result->get_risk_score();        // 42.5
$query_id = $result->get_query_id();          // for cross-referencing in MaxMind dashboard
$funds    = $result->get_funds_remaining();   // USD remaining on the account
$warnings = $result->get_warnings();          // any non-fatal warnings

Configuration

$client = new Client(
    'account-id',
    'license-key',
    [
        'cache_enabled' => true,    // default true
        'cache_ttl'     => 600,     // seconds; default 10 min
        'cache_prefix'  => 'mm_',   // transient key prefix
    ]
);

Request payload

The check_score() payload mirrors MaxMind's spec. The minimum is device.ip_address, but pass everything you have — minFraud's score quality scales with how much context you give it.

Useful fields beyond the basics:

$client->check_score( [
    'device'  => [
        'ip_address' => '203.0.113.42',
        'user_agent' => $_SERVER['HTTP_USER_AGENT'] ?? '',
    ],
    'email'   => [ 'address' => 'alice@example.com' ],
    'account' => [ 'user_id' => '42' ],
    'billing' => [ 'country' => 'US', 'postal' => '90210' ],
    'shipping' => [ 'country' => 'US', 'postal' => '90210' ],
    'payment' => [ 'processor' => 'stripe' ],
    'event'   => [ 'type' => 'purchase' ],
] );

Error handling

Errors come back as WP_Error rather than an empty Score, so you don't accidentally treat an auth failure like a 0 score:

$result = $client->check_score( $payload );

if ( is_wp_error( $result ) ) {
    $code    = $result->get_error_code();    // 'minfraud_api_error', 'minfraud_bad_response', etc.
    $message = $result->get_error_message();
    $data    = $result->get_error_data();    // includes HTTP status when relevant

    // Fall back to your own rules, log, etc.
}

Possible error codes:

• minfraud_missing_credentials — account ID / license key not provided
• minfraud_api_error — MaxMind returned a non-2xx with an error body
• minfraud_bad_response — couldn't decode the JSON
• http_request_failed — WordPress transport error (passed through verbatim)

Why not the official SDK?

MaxMind ships an official PHP SDK that you can absolutely use. This library exists for projects that want a smaller surface area — it's framework-aware (transient cache, wp_remote_* transport, no Composer-level Guzzle / PSR-7 deps) and exposes only the Score endpoint, which is what most rule engines actually need.

If you need Insights or Factors (subscores for IP location, email reputation, device, etc.), use the official SDK or open an issue.

License

GPL-2.0-or-later