Partner API

Resell our Vietnam eSIM plans from your own site or shop. You hold a prepaid wallet with us, place orders over HTTPS, and receive the activation code and a QR image to give your own customer. We never contact your customer.

Authentication

One bearer token per dealer, issued by us. Send it on every request. It never goes in the URL — URLs sit in proxy logs, browser history and our own access logs.

Authorization: Bearer YOUR_TOKEN
# or, if your HTTP client makes that awkward:
X-Partner-Token: YOUR_TOKEN

A wrong token, a paused account and an account that is not in dealer mode all return the same 401 unauthorized. That is deliberate: distinguishing them would tell a caller which tokens exist.

1. List plans

GET https://simvietnam.telebox.vn/api/partner/plans

Public, no token needed. Prices are in USD and are what you are charged unless we have agreed a dealer rate with you.

Delivered instantly (10)

Built to order (3)

Physical SIM cards are not sold through this API. Handing one over needs your customer's hotel address or flight details, and we would rather not hold personal data about someone we have no relationship with.

2. Place an order

POST https://simvietnam.telebox.vn/api/partner/orders
Content-Type: application/json

# instant plan — no date
{ "slug": "mobifone-7days", "quantity": 1, "ref": "YOUR-ORDER-ID" }

# made-to-order plan — date required
{ "slug": "vietnam-esim-unlimited-7days",
  "receiveDate": "2026-10-01",
  "quantity": 1,
  "ref": "YOUR-ORDER-ID" }

Always send a ref. It is your own order id. If the network drops after we received the request, calling again with the same ref returns the original order instead of placing a second one and charging you twice.

An instant order comes back already delivered, with the codes in sims:

{
  "ok": true,
  "orderNumber": "ORD-20261001-1234",
  "ref": "YOUR-ORDER-ID",
  "delivery": "instant",
  "state": "ready",
  "sims": [
    { "lpa": "LPA:1$rsp.example.com$ABC123",
      "serial": "8984...",
      "qrUrl": "https://simvietnam.telebox.vn/api/esim/qr/ORD-20261001-1234/0?s=..." }
  ],
  "pricing": { "unitPriceUSD": 9.9, "totalUSD": 9.9, "tier": null, "note": "..." },
  "walletBalanceUSD": 90.1
}

A made-to-order order comes back as awaiting_sim with sims: null. Collect it later with step 3.

Batch limits, and why they are low

• Instant: up to 5 per order. Each one is a real purchase from our upstream carrier partner, whose buy endpoint rate-limits bulk requests. We refuse a batch we might only half-fill rather than leave you having promised more SIMs than arrived.
• Made to order: 1 per order. An order carries exactly one activation code, because each SIM is built individually. Send one call per SIM, each with its own ref.

3. Collect the SIM

GET https://simvietnam.telebox.vn/api/partner/orders?order=ORD-20261001-1234
GET https://simvietnam.telebox.vn/api/partner/orders            # your most recent orders

You only ever see your own orders. Each one reports a state:

• awaiting_sim — paid, not built yet. For a made-to-order plan this is normal until the receive date.
• ready — sims holds the activation code, the serial and a QR image URL.
• cancelled_refunded — we could not source it and your wallet was already refunded in full. Nothing is pending on your side.

Poll once around the receive date, not in a loop. We tell you when to come back in hint.

The QR image

qrUrl is a permanent, signed link you can embed directly in your own email — it needs no token, so an email client can load it. The activation code itself is never in that URL: anyone who forwards your email forwards a picture, not a key. The image is marked noindex and never cached by shared proxies.

You can also draw your own QR from the lpa string — it is a standard GSMA SGP.22 activation code.

Wallet and pricing

You top up in advance; every order debits the wallet. If the balance is short we refuse the order with 402 insufficient_wallet and tell you exactly how much is missing — nothing is charged.

pricing.tier is null when no dealer rate has been agreed for that quantity, and you are charged the normal retail price. We say so in pricing.noterather than calling retail a “dealer price”.

If an instant order fails after the debit — upstream out of stock, upstream rate limit — we refund the wallet in full, cancel the order, and return 503 fulfillment_failed. It is safe to retry, including with the same ref.

Rate limits

Over the limit you get 429 with a Retry-After header. Honour it — retrying immediately just keeps you blocked. Reads and writes are counted separately, so hitting the write limit never stops you collecting a SIM you have already paid for.

Errors

Every failure returns ok: false, a stable error code to branch on, and a message written for whoever is reading the log. Branch on the code, show the message.

What we deliberately do not do

• We never email your customer. Their eSIM data comes back through this API and nowhere else. We do not ask for their name or address, and we do not put our own referral discount in front of them — they are your customer, not ours.
• No webhooks yet. A webhook needs you to run a public endpoint around the clock, and when it is down the SIM exists but reaches nobody. Polling has no state to lose. Ask us if you need push and we will build it on top of this.
• No subscriber number in the response. The unlimited line is data-only, and the metered plans that do carry a +84 number do not receive app or bank verification codes. Do not sell either as an OTP-capable number.

Getting a token

Email admin@telebox.vn with the shop or site you sell from and roughly how many SIMs a month you expect. We are Telebox, an authorized Viettel and Vinaphone dealer with a real shop in Hanoi — dealer since 2009.

Plan list, batch limits, date window and rate limits on this page are read from the running system, not typed in by hand.