Quickstart

Three steps from zero to your first eSIM:

1. Get a key — apply for a B2B account. You start in sandbox, so you can build the whole integration before funding anything.
2. Call the API — every request carries your key as a Bearer token (below).
3. Go live — top up your wallet and we flip your key to live; the same calls now provision real eSIMs.

shellKEY="tb2b_sk_xxxxxxxxxxxxxxxxxxxx"

# list Japan plans with your wholesale price
curl -s -H "Authorization: Bearer $KEY" \
  "https://esim.turnaa.cloud/wp-json/turnaa/v1/b2b/catalog?country=jp&days=7"

Conventions

Authentication

Send your API key as a Bearer token on every request. Keys are shown once in your dashboard and stored only as a hash — roll a new one anytime (the old key stops working immediately).

httpAuthorization: Bearer tb2b_sk_xxxxxxxxxxxxxxxxxxxx

Errors

Errors use standard HTTP status codes and a JSON body with a machine-readable code:

json{ "code": "insufficient_funds",
  "message": "Wallet balance too low — top up required",
  "data": { "status": 402 } }

Rate limits & fair use

Poll an order at most once every 3 seconds. The catalog changes only a few times a day — cache it on your side for ~6 hours rather than fetching per page view. Bulk orders should send one request per plan_id with a qty rather than many parallel calls.

GET /b2b/catalog

Every orderable plan with your wholesale price and the suggested retail price.

shellcurl -s -H "Authorization: Bearer $KEY" \
  "https://esim.turnaa.cloud/wp-json/turnaa/v1/b2b/catalog?country=jp&days=7"

json[
  {
    "plan_id": 3732,
    "name": "Japan · Unlimited · 1 day",
    "data_mb": 3072,
    "duration_days": 1,
    "unlimited": true,
    "partner_price": 3.54,
    "retail_price": 9.45,
    "currency": "USD"
  }
]

GET /b2b/suggest

Trip-aware plan picker: give a destination and the trip dates (or a day count) and we return the plans that fit, cheapest first, each flagged fits_trip.

shellcurl -s -H "Authorization: Bearer $KEY" \
  "https://esim.turnaa.cloud/wp-json/turnaa/v1/b2b/suggest?country=it&start=2026-08-01&end=2026-08-09"

json{
  "trip_days": 9,
  "fit": [
    { "plan_id": 812, "name": "Italy · 3 GB · 15 days",
      "duration_days": 15, "partner_price": 4.92, "retail_price": 11.99,
      "unlimited": false, "currency": "USD", "fits_trip": true }
  ],
  "all": [ /* every plan for the country, fits_trip true/false */ ]
}

GET /b2b/balance

Your prepaid wallet balance and the current mode of your key.

json{ "balance": 250.00, "currency": "USD", "mode": "live" }

POST /b2b/orders

Order one or more eSIMs for a plan. The unit price is debited from your wallet; the response carries the eSIM activation payload.

shellcurl -s -X POST \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"plan_id":3732,"qty":1,"idempotency_key":"order-abc-123"}' \
  "https://esim.turnaa.cloud/wp-json/turnaa/v1/b2b/orders"

json{
  "id": 4821,
  "status": "completed",
  "mode": "live",
  "unit_price": 3.54,
  "total": 3.54,
  "currency": "USD",
  "balance": 246.46,
  "payload": {
    "esims": [
      {
        "iccid": "89371034000059xxxxx",
        "activation_code": "LPA:1$rsp.example.com$XXXXXXXX",
        "qr_note": "Encode activation_code as a QR for the customer"
      }
    ]
  }
}

GET /b2b/orders/{id}

Fetch a single order (only your own). Use it to poll a processing order until the payload.esims array is populated.

shellcurl -s -H "Authorization: Bearer $KEY" \
  "https://esim.turnaa.cloud/wp-json/turnaa/v1/b2b/orders/4821"

GET /b2b/ledger

Your wallet statement — every movement, newest first.

json[
  { "id": 5, "type": "debit", "amount": 3.54, "balance_after": 246.46,
    "note": "Order #4821", "order_id": 4821, "created_at": "2026-07-15 09:12:04" }
]

Order lifecycle

Idempotency

Send a unique idempotency_key with every POST /orders. If a request is retried (network blip, timeout) with the same key, we return the original order — flagged "idempotent": true — and never charge twice. Use one key per intended purchase (e.g. your own order id).

Sandbox & live

Every account starts in sandbox. All endpoints behave identically, but orders return a clearly-fake payload and nothing is charged:

json{
  "status": "sandbox_completed",
  "payload": { "esims": [
    { "iccid": "SANDBOX1234567890123",
      "activation_code": "LPA:1$sandbox.turnaa.cloud$TEST-XXXXXXXXXXXX",
      "qr_note": "SANDBOX — no real eSIM issued, no wallet charge" }
  ]}
}

Build and test the full flow against sandbox. When you top up your wallet we switch your key to live — the same code then provisions real eSIMs. Check mode from /balance at runtime if you branch on it.

Webhooks

Set an HTTPS webhook URL from your dashboard (Developer tab). We POST a signed JSON event so you don’t have to poll:

jsonPOST your-webhook-url
X-Turnaa-Event: order.completed
X-Turnaa-Signature: sha256=9f86d081...

{ "event": "order.completed",
  "created": "2026-07-15T09:12:04+00:00",
  "data": { "order_id": 4821, "status": "completed", "mode": "live",
            "total": 3.54, "currency": "USD", "esims": [ ... ] } }

Verify every delivery — compute HMAC-SHA256(raw_body, signing_secret) and compare it to the X-Turnaa-Signature header (constant-time). The signing secret is shown in your dashboard when you save the URL.

php$raw = file_get_contents('php://input');
$sig = 'sha256=' . hash_hmac('sha256', $raw, $signing_secret);
if (!hash_equals($sig, $_SERVER['HTTP_X_TURNAA_SIGNATURE'] ?? '')) {
    http_response_code(400); exit;
}
$event = json_decode($raw, true);

nodeconst crypto = require('crypto');
const sig = 'sha256=' + crypto.createHmac('sha256', SIGNING_SECRET)
                              .update(rawBody).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(req.get('X-Turnaa-Signature')||'')))
  return res.sendStatus(400);

shortcode
0.1 GB7 days$2.99Buy now0.5 GB7 days$3.13Buy now0.5 GB/day1 day$3.45Buy now1 GB7 days$4.09Buy now1 GB/day1 day$4.41Buy now2 GB/day1 day$6.97Buy now3 GB15 days$7.29Buy now3 GB30 days$7.61Buy now3 GB/day1 day$8.89Buy now5 GB30 days$10.49Buy now5 GB/day1 day$13.11Buy now10 GB30 days$16.89Buy now
Plans provided by Turnaa

Get access

A B2B account ties your API key, wallet and order history to one Turnaa login. Approval typically takes one business day, and you build entirely in sandbox until you are ready.