PHP

require 'mmolove-referral.php';

// referee_identity is REQUIRED on registered — the first-touch anchor:
$res = mmolove_referral_send($MMOLOVE_SECRET, $MMOLOVE_SERVER_ID, 'registered', $mmref, [
    'referee_identity' => 'player-7842',
    'server_event_id'  => 'reg-7842',   // idempotency key, stable across retries
]);

// When they hit your "qualified" bar:
$res = mmolove_referral_send($MMOLOVE_SECRET, $MMOLOVE_SERVER_ID, 'qualified', $mmref, [
    'server_event_id' => 'qual-7842',
]);

if ($res['status'] !== 200) {
    error_log("referral send failed: {$res['status']} " . json_encode($res['body']));
}

<?php
// config — load from env / secrets manager; NEVER hardcode in a public repo.
const MMOLOVE_ENDPOINT = 'https://mmolove.com/api/referral/events';
$MMOLOVE_SECRET    = getenv('MMOLOVE_REFERRAL_SECRET');   // from the Referrals tab
$MMOLOVE_SERVER_ID = getenv('MMOLOVE_SERVER_ID');         // your server id

<?php
/**
 * mmolove-referral.php — single-file Referral Kit client (vote-callback style).
 *
 * Reports a referral lifecycle event to MMOLove with an HMAC-signed body.
 * @return array{status:int, body:string}
 */
function mmolove_send_event(string $secret, string $serverId, string $event, array $extra): array
{
    // Build the body ONCE. We sign these exact bytes and send these exact bytes.
    $payload = array_merge([
        'event'     => $event,            // 'registered' | 'qualified'
        'server_id' => $serverId,
        'ts'        => time(),            // your event time (your logs/ordering)
    ], $extra);
    $raw = json_encode($payload, JSON_UNESCAPED_SLASHES);

    // HMAC-SHA256 over "<t>.<rawBody>" (timestamp, a dot, then the raw body).
    $t   = time();
    $mac = hash_hmac('sha256', $t . '.' . $raw, $secret);   // lowercase hex
    $sig = "t={$t},v1=sha256={$mac}";

    $ch = curl_init(MMOLOVE_ENDPOINT);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $raw,                      // <-- the SAME bytes we signed
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 10,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            "X-MMOLove-Signature: {$sig}",
        ],
    ]);
    $body   = curl_exec($ch);
    $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $err    = curl_error($ch);
    curl_close($ch);

    if ($body === false) {
        // Transport failure (DNS/timeout). Treat like a 5xx: retry with backoff.
        return ['status' => 0, 'body' => $err];
    }
    return ['status' => $status, 'body' => $body];
}

<?php
// On your registration page, BEFORE creating the account.
$mmref = $_GET['mmref'] ?? ($_COOKIE['mmref'] ?? null);
if ($mmref !== null && $mmref !== '') {
    // Store it on the new account row so you can echo it back below.
    // e.g. INSERT INTO accounts (..., mmref) VALUES (..., :mmref)
    $newAccount->mmref = $mmref;
}

<?php
if (!empty($newAccount->mmref)) {
    $res = mmolove_send_event($MMOLOVE_SECRET, $MMOLOVE_SERVER_ID, 'registered', [
        'token'            => $newAccount->mmref,            // the captured token
        'referee_identity' => (string) $newAccount->id,      // STABLE id
        'server_event_id'  => 'reg-' . $newAccount->id,      // idempotency key
    ]);
    mmolove_handle_result($res);   // see error handling below
}

<?php
function on_player_qualified(object $player): void
{
    global $MMOLOVE_SECRET, $MMOLOVE_SERVER_ID;

    if (empty($player->mmref)) {
        return;   // not a referred player — nothing to report
    }

    $res = mmolove_send_event($MMOLOVE_SECRET, $MMOLOVE_SERVER_ID, 'qualified', [
        'token'           => $player->mmref,                 // SAME token as register
        'server_event_id' => 'qual-' . $player->id,          // NEW idempotency key
    ]);

    if (mmolove_handle_result($res)) {
        // MMOLove credited the referrer. Now YOU grant the reward in-game.
        grant_referrer_reward_for($player);
    }
}

<?php
/** @return bool true if the event was accepted (a 200 of any flavour). */
function mmolove_handle_result(array $res): bool
{
    $status = $res['status'];
    $data   = json_decode($res['body'] ?: 'null', true);

    if ($status === 200) {
        // {ok:true,...} — advanced, OR duplicate, OR first_touch_conflict, OR test.
        // All are terminal; do NOT retry.
        return true;
    }

    if ($status === 0 || $status >= 500) {
        // Transport/5xx — safe to retry with backoff (same server_event_id).
        mmolove_enqueue_retry($res);
        return false;
    }

    // 4xx — a bug in the request; retrying won't help. Log and fix.
    $err = $data['error'] ?? 'unknown';
    error_log("[mmolove] event rejected ({$status}): {$err}");
    return false;
}

<?php
$res = mmolove_send_event($MMOLOVE_SECRET, $MMOLOVE_SERVER_ID, 'registered', [
    'token'            => '<mmref>',
    'referee_identity' => '<player>',
    'server_event_id'  => 'test-1',
    'test'             => true,
]);
// Expect: status 200, body {"ok":true,"test":true}