Docs / Server verify / PHP

Verify Playtcha from PHP

This page is the server-side contract for PHP apps. Your backend receives the client-submitted result token, posts it to /v1/verify with your secret key, and only then continues the request.

Minimal example

The minimal correct contract is still { secret, token } over JSON with a bounded timeout.

verify_playtcha.php

<?php
function verify_playtcha(string $token): array {
    if ($token === '') {
        return [
            'success' => false,
            'error' => ['code' => 'missing_token', 'message' => 'Missing result token'],
        ];
    }

    $ch = curl_init('https://playtcha.com/v1/verify');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode([
            'secret' => $_ENV['PLAYTCHA_SECRET'],
            'token' => $token,
        ]),
        CURLOPT_TIMEOUT => 5,
    ]);

    $body = curl_exec($ch);
    if ($body === false) {
        return [
            'success' => false,
            'error' => ['code' => 'network_error', 'message' => "Couldn't reach Playtcha verify"],
        ];
    }

    return json_decode($body, true) ?? [
        'success' => false,
        'error' => ['code' => 'network_error', 'message' => "Couldn't reach Playtcha verify"],
    ];
}

Production-ready example

Log the upstream error envelope server-side, and remember that degraded still means the user verified successfully.

verify_playtcha_prod.php

<?php
// Implements the fail-open contract.
//   5xx / network    -> log + treat as verified (unless PLAYTCHA_FAIL_CLOSED=1)
//   4xx              -> reject deterministically
//   429              -> reject + honor Retry-After (don't tighten retries)
//
// Returns a helper-shaped result. The 'ok' flag is local —
// Playtcha's wire format has no success:false field on errors.
function verify_playtcha(string $token): array {
    if ($token === '') {
        return ['ok' => false, 'status' => 0, 'unavailable' => false,
                'error' => ['code' => 'missing_token', 'message' => 'Missing result token']];
    }

    $payload = json_encode([
        'secret' => getenv('PLAYTCHA_SECRET'),
        'token'  => $token,
    ]);

    $ch = curl_init('https://playtcha.com/v1/verify');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS     => $payload,
        CURLOPT_TIMEOUT        => 5,
    ]);

    $body   = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

    if ($body === false) {
        return ['ok' => false, 'status' => 0, 'unavailable' => true,
                'error' => ['code' => 'network_error', 'message' => "Couldn't reach Playtcha verify"]];
    }

    $data = json_decode($body, true) ?? [];

    if ($status >= 500) {
        return ['ok' => false, 'status' => $status, 'unavailable' => true,
                'error' => ['code' => 'verifier_unavailable', 'message' => '5xx']];
    }
    if ($status >= 400) {
        // 4xx: upstream error envelope { error: { code, message, request_id, hint?, host? } }
        return ['ok' => false, 'status' => $status, 'unavailable' => false,
                'error' => $data['error'] ?? ['code' => 'unknown_error', 'message' => '']];
    }
    return ['ok' => true, 'data' => $data];
}

// Example usage
$fail_closed = getenv('PLAYTCHA_FAIL_CLOSED') === '1';
$result = verify_playtcha($_POST['playtcha-token'] ?? '');

if (!$result['ok']) {
    if ($result['unavailable']) {
        error_log('playtcha.verify.unavailable status=' . $result['status']);
        if ($fail_closed) {
            http_response_code(503);
            echo json_encode(['error' => 'verifier_unavailable']);
            exit;
        }
        // fall through — treat as verified
    } else {
        // 409 already_redeemed is a security signal: replay, stuck retry, or duplicate POST.
        // Log with request_id at warn level — do not silently retry.
        error_log(sprintf(
            'playtcha.verify.failed status=%s code=%s request_id=%s',
            $result['status'],
            $result['error']['code'] ?? '',
            $result['error']['request_id'] ?? ''
        ));
        http_response_code(400);
        echo json_encode(['error' => 'verification-failed']);
        exit;
    }
} elseif (!empty($result['data']['degraded'])) {
    error_log('playtcha.verify.degraded reason=' . ($result['data']['degraded_reason'] ?? 'unknown'));
}

Common gotchas

Do not send your secret key to the browser or render it into templates.
Fail open on 5xx and network errors; fail closed on 4xx. Opt into PLAYTCHA_FAIL_CLOSED=1 for high-fraud paths.
Treat degraded=true as success and log it as a quota-state event, not a failed human check.
409 already_redeemed is single-use-by-design. In production it means replay, stuck retry, or duplicate POST. Log with request_id at warn level — do not retry.
429 rate_limited_ip means per-IP throttle. Honor the Retry-After header; do not retry tighter than 1s.
The wire format has no success: false field on errors. The envelope is { error: { code, message, request_id, ... } }.
Return a generic verification error to the browser; keep the upstream error envelope in server logs.

Relevant failure codes

Status	Code	Meaning
401	`token_invalid`	Bad signature or claims. Often wrong env (live vs test).
401	`bad_secret`	Secret does not match the project. Config error.
404	`unknown_project`	Project deleted or never existed.
409	`already_redeemed`	Security signal. Single-use by design. Log with `request_id` at warn level.
410	`token_expired`	Result token TTL elapsed (5 minutes).
429	`rate_limited_ip`	Per-IP throttle. Response has `Retry-After` header.
500	`db_error`	Playtcha-side. Fail open.

Where to go next

Pair this with token lifecycle for the token model, or domain whitelist if your issue happens before verify on the public widget endpoints.