# 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:

| 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_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

```bash title="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.
