Partner API

Sell eSIMs under your own brand.

One REST API for the wholesale catalogue, instant back-to-back provisioning and live usage. Build against the free sandbox today — no account, no card, no waiting.

Try the sandbox Request live access

Partner currency: USD
Funding: EUR / GBP / JPY / USD
Provisioning: Instant, back-to-back
Coverage: 190+ destinations

Two payment options

PayNovus supports Visa, Mastercard and Maestro, plus Apple Pay and Google Pay where the partner’s currency channels and customer device support them. Local payment methods are only available where your connected hosted processor offers and approves them; PayNovus local payment channels are not integrated here yet. Unicorn checkout remains unavailable until provider-hosted entry and verified payment confirmations are approved.

Your own checkout

Collect card and wallet payments with your own acquirer, then call POST /api/public/partner/orders. Skybyte debits your wholesale USD balance and fulfils the order. Never order before your own processor confirms payment.

Skybyte-hosted PayNovus checkout

Connect your own PayNovus account in Payments. Create a payment link and send the returned payment_url to your customer. Cards and configured wallets pay into your account, not Skybyte’s. Enable the notification destination shown in Payments so closed browsers do not interrupt payment confirmation. Use GET /partner/esims with order_id to read fulfilment and your configured signed delivery webhook for eSIM updates.

Create a hosted payment link

curl -X POST https://skybytesim.com/api/public/partner/payment-links \
  -H "Authorization: Bearer sb_partner_your_key" \
  -H "Content-Type: application/json" \
  -d '{"sku":"SB-your-bundle","quantity":1,"reference":"sale-1001","customer_email":"customer@example.com","total":25,"currency":"USD","expires_in_hours":24}'

Repeat the same reference and details to receive the same link and original expiry. Changed details return reference_conflict. A used or expired link cannot make a second sale; use a new reference only for a genuinely new order. Your company handles retail tax and customer refunds through its own processor.

Card payments inside your app

Add embed_origin with your exact HTTPS app origin when creating a link. Place the returned embed_url in an iframe to keep customers in your app. Only that saved origin can frame the payment page; other Skybyte pages remain protected. Keep payment_url available as a secure browser fallback for unsupported devices or bank authentication. Your API key stays on your server.

Embed the returned checkout URL

<iframe title="Secure card payment" src="RETURNED_EMBED_URL"
  allow="payment" referrerpolicy="no-referrer"
  style="width:100%;height:900px;border:0"></iframe>

The frame sends skybyte.payment.status messages with order_id and status to the saved origin only. Check event.origin is https://skybytesim.com and event.source is your iframe before updating progress. Always verify payment and fulfilment through your server and signed webhooks; a browser message never authorises delivery. Changing embed_origin on a retry returns reference_conflict. Native WebViews, wallets and bank challenges require provider/device verification.

White label, delivery & webhooks

We act as your wholesaler and eSIM platform. Your customers see only your brand: upload your logo, colours, support contacts and email footer in the Partner Portal or via PATCH /branding.

Choose how each eSIM reaches your customer with the delivery field (or your portal default):

branded_email — we email the QR code and phone-by-phone install guide in your brand and the customer's language. Replies go to your support email.
webhook — we POST esim.ready (and later esim.activated) to your URL; your own email system delivers it.
none — we send nothing; use the API response.

Webhooks are signed: X-Skybyte-Signature: t=<ts>,v1=<hex> is HMAC-SHA256 of ts + "." + raw_body with your webhook secret. Reject anything older than 5 minutes. Failed deliveries retry 3 times and appear in the portal.

Hosted shop: switch on a ready-made branded shop at skybytesim.com/shop/<your-slug> with its own install guide. You earn the difference between retail (ex VAT) and your wholesale price on every sale. Custom domains on request.

Order with webhook delivery

curl -X POST https://skybytesim.com/api/public/partner/orders \
  -H "Authorization: Bearer sb_partner_your_key" \
  -H "Content-Type: application/json" \
  -d '{"sku":"SB-esim_10GB_15D_ES_V2","reference":"ord-1042",
       "customer_email":"traveller@example.com",
       "delivery":"webhook","customer_locale":"pt"}'

Verify a webhook (Node.js)

import crypto from "node:crypto";
const header = req.headers["x-skybyte-signature"] || "";
if (typeof header !== "string") return res.status(401).end();
const parts = Object.fromEntries(header.split(",").map(p => p.trim().split("=")));
const { t, v1 } = parts;
if (!t || !v1 || !/^[0-9a-f]{64}$/i.test(v1)) return res.status(401).end();
const expected = crypto.createHmac("sha256", process.env.SKYBYTE_WEBHOOK_SECRET)
  .update(`${t}.${rawBody}`).digest();
const fresh = Number.isFinite(Number(t)) && Math.abs(Date.now() / 1000 - Number(t)) < 300;
if (!fresh || !crypto.timingSafeEqual(Buffer.from(v1, "hex"), expected)) {
  return res.status(401).end();
}}

Authentication

Every request carries a bearer token. Live keys start with sb_partner_ and are issued by us when your partner account is approved. Sandbox keys start with sb_sandbox_ and work immediately.

Keys are hashed at rest and can be rotated or revoked at any time.
All traffic is TLS-only; CORS is open for integration testing. Keep production keys on your server, never in customer browser code. Limits per source IP: 120 reads and 30 writes per minute; a 429 includes Retry-After: 60.
Send a unique reference per order — it acts as the idempotency key. References are required; keep the same request body on retry. X-Api-Key is also supported.

Authorization header

curl https://skybytesim.com/api/public/partner/catalogue \
  -H "Authorization: Bearer sb_partner_your_key_here"

Endpoints

Base URL https://skybytesim.com. Prefix any path with /sandbox after /partner to hit the simulator.

GET/api/public/partner/catalogue

Your enabled bundles, priced in USD. Configure availability in the partner portal. Every item carries country_name, country_flag and coverage_detail (code, name, flag) so your storefront can show full names and flags; country and coverage stay two-letter codes for matching.

country (two-letter code, optional) · limit (max 500) · offset — follow next_offset to page through the full catalogue

POST/api/public/partner/orders

Buy a bundle back-to-back. We provision with the upstream carrier and return the eSIM activation details.

sku · quantity (1-10) · reference · customer_email · delivery (branded_email | webhook | none) · customer_locale (en, pt, es, fr, de, it, ar, ja, zh, ko)

GET/api/public/partner/esims

Status, data usage and expiry for eSIMs on your own orders.

order_id or iccid

POST/api/public/partner/payment-links

Create a Skybyte-hosted card / Apple Pay / Google Pay checkout through your own live PayNovus account. You remain the seller. Requires live approval, a USD channel and sufficient Skybyte balance; eSIMs issue only after verified payment.

sku · quantity (1–10) · reference · customer_email · total (customer amount in USD, not below wholesale) · currency (USD) · expires_in_hours (1–168, default 24) · embed_origin (optional exact HTTPS app origin). Returns payment_url, embed_url, order_id, expires_at. Live only; the sandbox does not charge customers.

GET/api/public/partner/branding

Your white-label brand and delivery settings (logo, colours, support contacts, email footer, default delivery, webhook URL).

PATCH/api/public/partner/branding

Update supported branding fields. Logos are uploaded in the Partner Portal.

brand_name · brand_color · accent_color · support_email · support_url · website_url · email_footer · default_delivery · webhook_url · default_locale · shop_headline

GET/api/public/partner/announcements

Product updates and API changes. Also available at /api/public/partner/sandbox/announcements.

Sandbox

The sandbox simulates the documented live API requests, delivery previews and common errors — but nothing is charged, provisioned or booked to a ledger. Use the public demo key below, or any key you invent that starts with sb_sandbox_.

Keys

Use sb_sandbox_demo, or any key starting with sb_sandbox_ followed by 1–100 letters, numbers, underscores or hyphens.

Orders

reference is required (1–120 letters, numbers, . _ : -). quantity defaults to 1. branded_email needs customer_email.

Status lookup

Use the order_id returned by the order. Lookup by ICCID only works in production.

Webhooks

Previews show raw_body, headers and the test secret whsec_sandbox_demo. No real request is sent.

Repeat requests

The same request returns the same result. History and changed-body conflicts are only tracked in production.

Going live

Swap /sandbox out of the path and use your live key from the partner portal once your account is approved.

1 · Fetch the sandbox catalogue

curl https://skybytesim.com/api/public/partner/sandbox/catalogue \
  -H "Authorization: Bearer sb_sandbox_demo"

2 · Place a sandbox order

curl -X POST https://skybytesim.com/api/public/partner/sandbox/orders \
  -H "Authorization: Bearer sb_sandbox_demo" \
  -H "Content-Type: application/json" \
  -d '{"sku":"SBX-PT-5GB-30D","quantity":1,"reference":"my-test-1","delivery":"none"}'

3 · Check status and usage

curl "https://skybytesim.com/api/public/partner/sandbox/esims?order_id=<order_id returned above>" \
  -H "Authorization: Bearer sb_sandbox_demo"

4 · Force an error path

# SBX-FAIL-CREDIT     -> 402 credit_limit_exceeded
# SBX-FAIL-PROVISION  -> 502 provisioning_failed
# SBX-FAIL-NOTFOUND   -> 404 sku_not_found
curl -X POST https://skybytesim.com/api/public/partner/sandbox/orders \
  -H "Authorization: Bearer sb_sandbox_demo" \
  -H "Content-Type: application/json" \
  -d '{"sku":"SBX-FAIL-CREDIT","quantity":1,"reference":"error-test-1","delivery":"none"}'

5 · White label: branding & delivery preview

curl -X PATCH https://skybytesim.com/api/public/partner/sandbox/branding \
  -H "Authorization: Bearer sb_sandbox_demo" \
  -H "Content-Type: application/json" \
  -d '{"brand_name":"My Travel Co","brand_color":"#112233","default_delivery":"webhook"}'

# Orders accept delivery + customer_locale and return a delivery_preview
curl -X POST https://skybytesim.com/api/public/partner/sandbox/orders \
  -H "Authorization: Bearer sb_sandbox_demo" \
  -H "Content-Type: application/json" \
  -d '{"sku":"SBX-PT-5GB-30D","reference":"webhook-test-1","delivery":"webhook","customer_locale":"de"}'

Errors

401 unauthorized	Missing, revoked or malformed API key.
400 invalid_body	Body failed validation — check field names and types.
404 sku_not_found	The SKU is unknown or no longer active.
402 insufficient_spendable_balance	Insufficient cleared USD balance. Funding in EUR, GBP or JPY converts at the agreed commercial rate.
402 credit_limit_exceeded	Sandbox-only legacy SBX-FAIL-CREDIT test scenario.
400 webhook_url_not_allowed	Webhook URLs must be public https addresses.
403 api_not_enabled	This company's service does not include live API orders.
409 paynovus_not_ready	Connect the partner's live PayNovus USD channel before creating payment links.
503 payment_link_unavailable	Temporary service failure. Retry with the same reference; do not create another sale.
502 provisioning_failed	Upstream carrier failed. The order is returned with detail; retry with the same reference.

Ready to go live?

Live access includes your selected USD wholesale bundles, a fully spendable prepaid balance, and settlement and a named account manager. Tell us your expected volume and target markets and we'll issue your keys.

Apply for a partner account Talk to support