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 — once we approve live access and your wallet has funds, generate a second key from the dashboard. Both keys stay valid side by side: the same code provisions real eSIMs when it calls with the live key, and keeps testing freely with the sandbox one.

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. A key is shown once, at the moment it is created, and stored only as a hash — after that your dashboard shows its last four characters so you can tell one from the other. Roll a key anytime; the old one stops working immediately.

You hold up to two keys, tb2b_sk_sandbox_… and tb2b_sk_live_…, and they are independent: rolling one leaves the other alone, and a sandbox key can never move real money or act on a real eSIM. Keep them server-side — a key in browser or app code is a key anyone can spend.

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.

Usage for a single eSIM is cached for 3 minutes per ICCID, so calling GET /esims/{iccid} in a tight loop returns the same numbers and buys you nothing; a top-up clears that cache immediately. To show a customer dashboard, read GET /esims — it comes from our own records and never touches the carrier.

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/esims

Every eSIM you have sold, newest first, with the install payload we stored at the time of sale. It is served from our own records, so paging through it is cheap and the carrier is never contacted.

shellcurl -s -H "Authorization: Bearer $KEY" \
  "https://esim.turnaa.cloud/wp-json/turnaa/v1/b2b/esims?limit=20"

json{
  "esims": [
    {
      "iccid": "8937103400005912345",
      "order_id": 4821,
      "plan": "Japan \· Unlimited \· 1 day",
      "mode": "live",
      "customer_email": "traveler@example.com",
      "created_at": "2026-07-15T09:12:04+00:00",
      "activation_code": "LPA:1$rsp-eu.simlessly.com$32B863FF...A8A9",
      "smdp_address": "rsp-eu.simlessly.com",
      "matching_id": "32B863FF...A8A9",
      "qr_url": "https://.../qr/8937103400005912345.png"
    }
  ],
  "count": 1
}

Paging is over orders, not eSIMs: an order with qty: 3 contributes three rows, so count can exceed limit. Fields the carrier did not supply are left out of the row rather than sent empty — check for presence, do not compare against "".

GET /b2b/esims/{iccid}

Live usage for one eSIM, merged with its install payload — one call answers both “how much is left” and “how do I install it”, so a customer-facing screen needs no second request.

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

json{
  "iccid": "8937103400005912345",
  "status": "active",
  "data_total_mb": 3072,
  "data_used_mb": 812,
  "data_left_mb": 2260,
  "expires_at": "2026-08-14T00:00:00+00:00",
  "topups_used": 0,
  "topups_left": 9,
  "plan": "Japan \· Unlimited \· 1 day",
  "order_id": 4821,
  "activation_code": "LPA:1$rsp-eu.simlessly.com$32B863FF...A8A9",
  "smdp_address": "rsp-eu.simlessly.com",
  "matching_id": "32B863FF...A8A9"
}

Data is reported in MB. topups_left counts down from nine: the carrier accepts at most nine top-ups per profile, ever, and there is no way to raise it. expires_at is null until the profile is first used.

GET /b2b/esims/{iccid}/topups

What can be added to this eSIM, priced for you. The list is carrier-specific — do not cache it across ICCIDs and do not assume a plan from the catalog can be topped up onto an unrelated profile.

json{
  "packages": [
    { "code": "TOPUP_JP_1GB_7D", "name": "Japan 1 GB / 7 days",
      "data_mb": 1024, "days": 7, "price": 2.46, "currency": "USD",
      "needs_days": false }
  ]
}

price is what leaves your wallet, priced by the same wholesale rule as the catalog. When needs_days is true the package extends validity and you must send a days value with the purchase — there is no sensible default for us to pick.

POST /b2b/esims/{iccid}/topup

Add data to an eSIM the traveler already installed. No new QR, nothing for them to do — the allowance lands on the existing profile.

shellcurl -s -X POST \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"package_code":"TOPUP_JP_1GB_7D","idempotency_key":"topup-abc-123"}' \
  "https://esim.turnaa.cloud/wp-json/turnaa/v1/b2b/esims/8937103400005912345/topup"

json{ "id": 4907, "status": "completed", "mode": "live",
  "iccid": "8937103400005912345", "package": "TOPUP_JP_1GB_7D",
  "total": 2.46, "currency": "USD", "balance": 244.00 }

POST /b2b/esims/{iccid}/{action}

Four actions on one shape — suspend, unsuspend, cancel, revoke. They differ in what they cost you and whether you can undo them.

shell# refundable: unused profile only
curl -s -X POST -H "Authorization: Bearer $KEY" \
  "https://esim.turnaa.cloud/wp-json/turnaa/v1/b2b/esims/$ICCID/cancel"

# permanent, no money back — the flag is deliberate
curl -s -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"confirm":true}' \
  "https://esim.turnaa.cloud/wp-json/turnaa/v1/b2b/esims/$ICCID/revoke"

json{ "iccid": "8937103400005912345", "action": "cancel",
  "status": "completed", "refunded": 3.54, "balance": 249.00,
  "note": null }

refunded is the unit price that eSIM was sold at — not the order total, since one order can carry several. It is 0 for every action except cancel. The refund lands in your ledger as a refund row the moment the carrier confirms.

GET /b2b/ledger

Your wallet statement — every movement, newest first.

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

Order lifecycle

Top-ups are recorded as orders too, so they appear in your ledger with their own id and move through the same statuses.

After the sale

Selling the eSIM is the easy half. Most support load lands in the week that follows, and each question maps to one call:

Two things are worth building into your own refund policy rather than discovering later. Cancel only works on an untouched profile — the minute the traveler installs and uses it, the carrier will not take it back, so a “30-day money back” promise costs you real money after first use. And suspending does not pause the clock: a 30-day plan suspended for a week still expires on day 30.

Idempotency

Send a unique idempotency_key with every POST /orders and every POST /esims/{iccid}/topup. If a request is retried — network blip, timeout, a queue that redelivers — the same key returns the original order, flagged "idempotent": true, and never charges twice. Use one key per intended purchase, such as your own order id.

On top-ups the key goes further: we hand it to the carrier as the transaction id, and the carrier collapses a repeat of the same id onto the first top-up. So the protection covers the whole chain, not just our side of it. That only holds if the key is stable across retries — generating a fresh one each attempt defeats the entire mechanism.

Sandbox & live

You get two keys, not one switch. Each request runs in the mode of the key that carried it, so staging and production can run the same code at the same time and never collide — and going live never costs you your test environment.

Every endpoint behaves the same in both modes and the response shapes match field for field, so going live is a key change and not a code change. Sandbox orders return an obviously fake payload and charge nothing:

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" }
  ]}
}

Usage, top-ups and the management actions all work on sandbox eSIMs: usage numbers are generated (stable per ICCID, so they do not jump between calls), and the top-up catalogue is the fixed set SANDBOX-TOPUP-1GB-7D, SANDBOX-TOPUP-3GB-30D, SANDBOX-TOPUP-5GB-30D, priced through the same wholesale rule live uses (on fixed test costs), so your margin maths is exercised too.

If you branch on mode, read it from /balance at boot and assert it matches the environment you think you are in.

Webhooks

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

eSIM events fire whichever way the action was taken — your API call, or one of our staff acting on a support ticket — so your records stay in step with ours either way.

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.65Buy now3 GB15 days$6.95Buy now3 GB30 days$7.25Buy now3 GB/day1 day$8.45Buy now5 GB30 days$9.41Buy now5 GB/day1 day$11.71Buy now10 GB30 days$15.01Buy 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.