PHP SDK.

No Composer dependencies, on purpose.

Runtime

PHP 7.3 through 8.5, with ext-curl and ext-json. That is the entire dependency list. Shops on old, frozen PHP are exactly the shops that need a fraud signal, so the SDK is written in PHP 7.3-compatible syntax.

Namespace

Heatrail\Sdk\, PSR-4, mapped to the archive’s src/ directory.

Where it comes from

The archive is served from the partner portal, and it is also bundled inside the WooCommerce plugin. It appears on the Downloads page once your application is approved, on the Free plan as much as on Pro. It is not on Packagist.

Every release is built reproducibly from a tagged commit and its SHA-256 is published on the API reference. Check the archive against that value before you vendor it.

spl_autoload_register(function (string $class): void {
    $prefix = 'Heatrail\\Sdk\\';

    if (strncmp($class, $prefix, strlen($prefix)) !== 0) {
        return;
    }

    $file = __DIR__ . '/heatrail-sdk/' . str_replace('\\', '/', substr($class, strlen($prefix))) . '.php';

    if (is_file($file)) {
        require $file;
    }
});

null means omit. It does not mean empty.

One method never throws. One always does.

$result = $client->check(array $payload, string $idempotencyKey): array;

['degraded' => true, 'score' => 0, 'reasons' => []]

use Heatrail\Sdk\HeatrailLabelException;

try {
    $confirmed = $client->label(
        $orderRef,
        'fraud',                       // fraud | chargeback | real
        $operatorIdentifier,           // recorded as labelled_by
        $idempotencyKey,
        [
            'reason_code'        => 'stolen_card',
            'evidence_type'      => 'merchant_confirmation',
            'order_value_bucket' => '100-250',
        ]
    );

    // ['ok' => true, 'incident_id' => '…']
} catch (HeatrailLabelException $e) {
    // Tell the operator. Do not record the label as applied.
}

explain(string $orderRef)

Re-reads the score, reasons and check time for one of your own orders. Fails soft like check(). Any failure returns ['degraded' => true, 'status' => …] and it never throws, because a read-only convenience must not take down an order screen. It is not queued, because there is nothing to replay and the operator clicks again.

health()

A signed liveness probe returning ['status' => 'up'] or ['status' => 'degraded']. Use it to verify credentials during setup. The queue drain calls it first on its own.

A custom checkout, end to end.

<?php

declare(strict_types=1);

use Heatrail\Sdk\HeatrailClient;
use Heatrail\Sdk\HeatrailLabelException;
use Heatrail\Sdk\Queue\FileQueueStore;

final class FraudSignal
{
    /** @var HeatrailClient */
    private $client;

    /** @var FileQueueStore */
    private $queue;

    public function __construct()
    {
        $this->queue = new FileQueueStore('/var/lib/heatrail/queue.jsonl');

        $this->client = HeatrailClient::forShop(
            (string) getenv('HEATRAIL_KEY_ID'),
            (string) getenv('HEATRAIL_API_SECRET'),
            (string) getenv('HEATRAIL_API_BASE'),
            [
                'network_salt' => (string) getenv('HEATRAIL_NETWORK_SALT'),
                'queue' => $this->queue,
                'logger' => static function (string $level, string $message, array $context): void {
                    error_log('[heatrail] ' . $level . ' ' . $message . ' ' . json_encode($context));
                },
            ]
        );
    }

    /**
     * Call once, straight after the order row exists and before the order is
     * handed to the payment provider.
     *
     * @return array{score: int, reasons: array}|null null = no signal
     */
    public function scoreOrder(Order $order): ?array
    {
        $payload = [
            'order_ref' => $order->reference,   // ^[A-Za-z0-9._:-]{1,128}$
            'ip' => $order->clientIp,           // required
            'context' => [
                'product_risk_class' => $order->hasGiftCard ? 'gift_card' : 'physical',
                'qty' => $order->itemCount,
                'amount_bucket' => self::amountBucket($order->totalEur),
                'account_age_class' => $order->isGuest ? 'new' : 'existing',
            ],
        ];

        if ($order->sessionId !== null) {
            $payload['session_ref'] = $order->sessionId;
        }

        // null means OMIT. Never send '', never hash a fallback.
        $emailHash = $this->client->hashEmail($order->email);

        if ($emailHash !== null) {
            $payload['email_h'] = $emailHash;
        }

        $phoneHash = $this->client->hashPhone($order->phone, 'EE');

        if ($phoneHash !== null) {
            $payload['phone_h'] = $phoneHash;
        }

        $result = $this->client->check($payload, self::checkKey($order->reference));

        // Fail-open: "no signal" is NOT "low risk". Say so in your own code.
        if (! empty($result['degraded'])) {
            return null;
        }

        return [
            'score' => isset($result['score']) ? (int) $result['score'] : 0,
            'reasons' => isset($result['reasons']) && is_array($result['reasons']) ? $result['reasons'] : [],
        ];
    }

    /**
     * Returns false when Heatrail did not confirm. Show that to the operator
     * and never record a label the API did not accept.
     */
    public function applyLabel(Order $order, string $label, string $reasonCode, string $operator): bool
    {
        try {
            $this->client->label(
                $order->reference,
                $label,                                  // fraud | chargeback | real
                $operator,
                self::labelKey($order->reference, $label),
                [
                    'reason_code' => $reasonCode,        // ignored for 'real'
                    'evidence_type' => 'merchant_confirmation',
                    'order_value_bucket' => self::amountBucket($order->totalEur),
                ]
            );

            return true;
        } catch (HeatrailLabelException $e) {
            error_log('[heatrail] label not confirmed: ' . $e->getMessage());

            return false;
        }
    }

    /** Run from cron, once a minute. */
    public function drain(): int
    {
        return $this->client->drainQueue($this->queue);
    }

    /**
     * Deterministic per order, and built from a hash so that an order
     * reference containing '.' or ':' still yields a key matching the API's
     * ^[A-Za-z0-9_-]{16,128}$.
     */
    private static function checkKey(string $orderRef): string
    {
        return 'chk-' . substr(hash('sha256', $orderRef . '|' . getenv('HEATRAIL_KEY_ID')), 0, 32);
    }

    private static function labelKey(string $orderRef, string $label): string
    {
        return 'lbl-' . substr(hash('sha256', $orderRef . '|' . $label), 0, 32);
    }

    private static function amountBucket(float $total): string
    {
        if ($total < 50) {
            return '0-50';
        }

        if ($total < 100) {
            return '50-100';
        }

        if ($total < 250) {
            return '100-250';
        }

        return $total < 500 ? '250-500' : '500+';
    }
}

The example uses typed properties and nullable return types, so it wants PHP 7.4 or newer. The SDK itself stays 7.3-compatible, but your code does not have to.

// In checkout, after the order exists:
$signal = new FraudSignal();
$assessment = $signal->scoreOrder($order);

if ($assessment !== null && $assessment['score'] >= 70) {
    $order->flagForManualReview($assessment['reasons']);
}

// The order continues regardless. There is no else branch that stops a sale.

// bin/heatrail-drain.php, from cron, every minute:
(new FraudSignal())->drain();