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": trueand"segments": 0, and the send answer includes the code astest_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:
| Number | Network | With a test key |
|---|---|---|
0599000001 | Jawwal | Sent successfully. The code is always 1234 (or 123456 for 6-digit codes). |
0569000001 | Ooredoo | Ooredoo number, sent successfully. The code is always 1234 (or 123456). |
0599000002 | Jawwal | The gateway refuses the message: 502 sms_failed. Nothing is charged. |
0599000003 | Jawwal | Answers 402 insufficient_balance, as if the account had no credit left. |
0599000004 | Jawwal | Answers 429 rate_limited with retry_after 30, as if the number had just received a code. |
0599000005 | Jawwal | Sent 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_leftgoes down and after 5 tries the status isfailed. - Invalid number:
12345answers422 invalid_phone;0521234567answers422 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, withIdempotent-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\"}"
echoWhat to test before going live
- The right code passes, and your server marks the number verified.
- A wrong code shows the tries left; the 5th wrong try asks for a new code.
0599000005(expired) asks for a new code.0599000002(message refused) and0599000003(no balance) show a friendly error and alert your team for the latter.0599000004(rate limited) shows a countdown usingretry_after.- Double-clicking "Send" sends one code.
- The browser never receives the API key, the verification
idor the code.