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.phpexamples/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']);