Getting started

Sandbox

Build and test the whole integration for free with test keys and sandbox numbers that simulate every outcome.

The sandbox is test keys (otp_test_…). They use the same endpoints, requests and answers as live keys, so moving to production is just changing the key. With a test key:

  • No text message is ever sent, and no credit is ever used.
  • Every answer has "test": true and "segments": 0, and the send answer includes the code as test_code.
  • It works as soon as you sign up, before your account is approved.
  • Test verifications are separate from live ones: they never cancel a real customer's code, never use up live limits, and can't be read with a live key.

Sandbox numbers

Any valid Jawwal or Ooredoo number works with a test key and gets a random code. These numbers give predictable results, so you (or your AI coding assistant) can test every branch of your code:

NumberNetworkWith a test key
0599000001JawwalSent successfully. The code is always 1234 (or 123456 for 6-digit codes).
0569000001OoredooOoredoo number, sent successfully. The code is always 1234 (or 123456).
0599000002JawwalThe gateway refuses the message: 502 sms_failed. Nothing is charged.
0599000003JawwalAnswers 402 insufficient_balance, as if the account had no credit left.
0599000004JawwalAnswers 429 rate_limited with retry_after 30, as if the number had just received a code.
0599000005JawwalSent successfully with code 1234 (or 123456), but the code has already expired: checking it answers status expired.

Sandbox numbers are exempt from the per-number limits, so tests can reuse them freely; the per-account limit still applies. With a live key they are ordinary numbers.

Other outcomes need no special number:

  • Wrong code: check any other code; attempts_left goes down and after 5 tries the status is failed.
  • Invalid number: 12345 answers 422 invalid_phone; 0521234567 answers 422 unsupported_network.
  • Rate limit on a real number: send twice to the same non-sandbox number within 30 seconds.
  • Retries: send twice with the same Idempotency-Key: the second answer is the first one again, with Idempotent-Replayed: true.

A complete sandbox run

examples/curl/sandbox-flow.sh
#!/usr/bin/env bash
# The whole flow with a test key: no message is sent and nothing is charged.
#   OTP_PS_API_KEY=otp_test_… ./sandbox-flow.sh
set -euo pipefail
BASE="${OTP_PS_BASE_URL:-https://otp.ps}"
AUTH="Authorization: Bearer ${OTP_PS_API_KEY:?Set OTP_PS_API_KEY to a test key}"

# 1. Send a code to the sandbox number (its code is always 1234).
SEND=$(curl -sS "$BASE/api/v1/verify/send" -H "$AUTH" -H "Content-Type: application/json" \
  -H "Idempotency-Key: sandbox-$(date +%s)" \
  -d '{"phone": "0599000001", "purpose": "verify", "locale": "en"}')
echo "$SEND"
ID=$(printf '%s' "$SEND" | sed -n 's/.*"id":"\([^"]*\)".*/\1/p')

# 2. A wrong code: valid is false, attempts_left goes down.
curl -sS "$BASE/api/v1/verify/check" -H "$AUTH" -H "Content-Type: application/json" -d "{\"id\": \"$ID\", \"code\": \"0000\"}"
echo

# 3. The right code: valid is true.
curl -sS "$BASE/api/v1/verify/check" -H "$AUTH" -H "Content-Type: application/json" -d "{\"id\": \"$ID\", \"code\": \"1234\"}"
echo

What to test before going live

  1. The right code passes, and your server marks the number verified.
  2. A wrong code shows the tries left; the 5th wrong try asks for a new code.
  3. 0599000005 (expired) asks for a new code.
  4. 0599000002 (message refused) and 0599000003 (no balance) show a friendly error and alert your team for the latter.
  5. 0599000004 (rate limited) shows a countdown using retry_after.
  6. Double-clicking "Send" sends one code.
  7. The browser never receives the API key, the verification id or the code.

View as Markdown