Examples

PHP

A PHP client (curl), a command-line sandbox demo, and session-based endpoints for a website form.

PHP 7.4+, the curl extension. The client and the demo are tested against the API's sandbox on every change.

Client

examples/php/OtpPs.php
<?php
// OTP.ps client for PHP 7.4+ (uses the curl extension). Server-side only.
//   OTP_PS_API_KEY=otp_test_… (sandbox) or otp_live_… (real messages)
//   OTP_PS_BASE_URL=https://otp.ps (optional)

class OtpPsException extends Exception
{
    public $status;
    public $errorCode;   // e.g. invalid_phone, rate_limited (see the errors reference)
    public $retryAfter;  // seconds, for rate_limited

    public function __construct(int $status, ?array $body)
    {
        parent::__construct($body['message'] ?? "OTP.ps answered HTTP $status");
        $this->status = $status;
        $this->errorCode = $body['error'] ?? 'unknown';
        $this->retryAfter = $body['retry_after'] ?? null;
    }
}

class OtpPs
{
    private $key;
    private $base;

    public function __construct(?string $apiKey = null, ?string $baseUrl = null)
    {
        $this->key = $apiKey ?? getenv('OTP_PS_API_KEY');
        $this->base = rtrim($baseUrl ?? (getenv('OTP_PS_BASE_URL') ?: 'https://otp.ps'), '/');
        if (!$this->key) {
            throw new RuntimeException('OTP_PS_API_KEY is not set');
        }
    }

    /** Sends a code. Returns the verification (with test_code when using a test key). */
    public function sendCode(string $phone, string $purpose = 'verify', ?string $locale = null, ?string $idempotencyKey = null): array
    {
        $body = ['phone' => $phone, 'purpose' => $purpose];
        if ($locale) {
            $body['locale'] = $locale;
        }
        return $this->request('POST', '/verify/send', $body, $idempotencyKey ? ["Idempotency-Key: $idempotencyKey"] : []);
    }

    /** Checks what the customer typed. Trust only $result['valid'] === true. */
    public function checkCode(string $id, string $code): array
    {
        return $this->request('POST', '/verify/check', ['id' => $id, 'code' => $code]);
    }

    public function balance(): array
    {
        return $this->request('GET', '/balance');
    }

    private function request(string $method, string $path, ?array $body = null, array $headers = []): array
    {
        $ch = curl_init($this->base . '/api/v1' . $path);
        curl_setopt_array($ch, [
            CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 15,
            CURLOPT_HTTPHEADER => array_merge(['Authorization: Bearer ' . $this->key, 'Content-Type: application/json'], $headers),
        ]);
        if ($body !== null) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
        }
        $raw = curl_exec($ch);
        if ($raw === false) {
            $error = curl_error($ch);
            curl_close($ch);
            throw new RuntimeException("OTP.ps could not be reached: $error");
        }
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        $data = json_decode($raw, true);
        if ($status >= 400) {
            throw new OtpPsException($status, is_array($data) ? $data : null);
        }
        return $data;
    }
}

Sandbox demo

OTP_PS_API_KEY=otp_test_… php demo.php
examples/php/demo.php
<?php
// Sandbox walk-through from the command line:
//   OTP_PS_API_KEY=otp_test_… php demo.php
require __DIR__ . '/OtpPs.php';

$otp = new OtpPs();
$sent = $otp->sendCode('0599000001', 'verify', 'en', 'php-demo-' . bin2hex(random_bytes(4)));
echo "Sent {$sent['id']} to {$sent['to']} (status {$sent['status']})\n";

$wrong = $otp->checkCode($sent['id'], '0000');
echo 'Wrong code: valid=' . var_export($wrong['valid'], true) . ", attempts_left={$wrong['attempts_left']}\n";

$right = $otp->checkCode($sent['id'], '1234'); // the sandbox number's fixed code
echo 'Right code: valid=' . var_export($right['valid'], true) . ", status={$right['status']}\n";

try {
    $otp->sendCode('0521234567');
} catch (OtpPsException $e) {
    echo "Israeli number refused: {$e->errorCode}\n";
}

Endpoints for a form

examples/php/endpoints.php
<?php
// Plain-PHP endpoints for a website form:
//   POST endpoints.php?action=send   phone=…
//   POST endpoints.php?action=check  code=…
// The verification id and the number stay in the PHP session; the browser never sees them.
require __DIR__ . '/OtpPs.php';
session_start();
header('Content-Type: application/json');

function reply(int $status, array $body): void
{
    http_response_code($status);
    echo json_encode($body);
    exit;
}

$otp = new OtpPs();
$action = $_GET['action'] ?? '';

if ($action === 'send') {
    // Your own limit per visitor, so nobody can drain your balance.
    $_SESSION['otp_sends'] = array_filter($_SESSION['otp_sends'] ?? [], fn($t) => $t > time() - 900);
    if (count($_SESSION['otp_sends']) >= 5) {
        reply(429, ['error' => 'rate_limited']);
    }
    $_SESSION['otp_sends'][] = time();
    try {
        $v = $otp->sendCode((string)($_POST['phone'] ?? ''), 'verify', ($_POST['locale'] ?? 'ar') === 'en' ? 'en' : 'ar');
        $_SESSION['otp_pending'] = ['id' => $v['id'], 'phone' => (string)$_POST['phone']];
        reply(200, ['sent' => true, 'to' => $v['to'], 'expiresAt' => $v['expires_at']]);
    } catch (OtpPsException $e) {
        reply($e->status === 429 ? 429 : 400, ['error' => $e->errorCode, 'retryAfter' => $e->retryAfter]);
    }
}

if ($action === 'check') {
    $pending = $_SESSION['otp_pending'] ?? null;
    if (!$pending) {
        reply(400, ['error' => 'no_code']);
    }
    try {
        $r = $otp->checkCode($pending['id'], (string)($_POST['code'] ?? ''));
    } catch (OtpPsException $e) {
        reply(400, ['error' => $e->errorCode]);
    }
    if ($r['valid'] === true) {
        unset($_SESSION['otp_pending']);
        $_SESSION['verified_phone'] = $pending['phone']; // trust this, set on the server
        reply(200, ['verified' => true]);
    }
    if ($r['status'] !== 'pending') {
        unset($_SESSION['otp_pending']);
    }
    reply(400, ['verified' => false, 'status' => $r['status'], 'attemptsLeft' => $r['attempts_left']]);
}

reply(404, ['error' => 'unknown_action']);

View as Markdown