PHP SDK.

Composer sõltuvusi ei ole, teadlikult.

Käitusaeg

PHP 7.3 kuni 8.5, koos ext-curl ja ext-json. See on kogu sõltuvuste nimekiri. Poed vanal, külmutatud PHP-l on täpselt need poed, kes pettusesignaali vajavad, seega SDK on kirjutatud PHP 7.3 ühilduvas süntaksis.

Nimeruum

Heatrail\Sdk\, PSR-4, seotud arhiivi src/ kataloogiga.

Kust ta tuleb

Arhiivi serveeritakse partnerportaalist, ja ta on ka WooCommerce lisa sees. Ta ilmub Downloads lehele, kui teie taotlus on kinnitatud, nii Free kui Pro plaanil. Teda ei ole Packagistis.

Iga väljalase ehitatakse sildistatud commitist reprodutseeritavalt ja tema SHA-256 avaldatakse API viites. Kontrollige arhiiv selle väärtuse vastu enne, kui te ta vendorite.

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 tähendab jätmist. See ei tähenda tühja.

Üks meetod ei viska kunagi. Üks viskab alati.

$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)

Loeb skoori, põhjused ja kontrolli aja uuesti ühe teie enda tellimuse kohta. Pehme tõrge nagu check(). Iga tõrge tagastab ['degraded' => true, 'status' => …] ja ta ei viska kunagi, sest ainult lugemiseks mõeldud mugavus ei tohi tellimuse ekraani maha võtta. Järjekorda teda ei panda, sest korduseks ei ole midagi ja operaator klõpsab uuesti.

health()

Allkirjastatud elussond, mis tagastab ['status' => 'up'] või ['status' => 'degraded']. Kasutage teda volituste kontrollimiseks seadistamise ajal. Järjekorra tühjendus kutsub teda esimesena ise.

Kohandatud kassa, otsast lõpuni.

<?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+';
    }
}

Näide kasutab tüübitud omadusi ja nullable tagastustüüpe, seega ta tahab PHP 7.4 või uuemat. SDK ise jääb 7.3 ühilduvaks, aga teie kood ei pea.

// 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();