Mobisim Public API

Sell eSIMs from your own storefront. Browse the catalogue assigned to your company, buy packages at your negotiated prices, and read back each order's eSIM profile and live data usage — over plain REST with JSON payloads.

Every request is authenticated with a merchant key pair and is scoped to one company: you only ever see your own catalogue, orders and wallet. There is no login step and no token to refresh.

Getting Started

Follow these steps to make your first API call.

Base URL

All API endpoints are relative to this base URL.

Response shape

Every endpoint returns the same envelope, on success and on failure alike. Write your unwrapping and your error handling once.

{
  "success": true,
  "message": null,
  "data": { ... },      // or [ ... ], or null on failure
  "totalCount": 1274,
  "page": 1,
  "pageSize": 50,
  "totalPages": 26,
  "stats": {}
}

Authentication

Every request under /api must carry both headers below. Together they identify your company and authorise the request; the documentation pages themselves are open.

curl 'https://partners-api.mobisim.com/api/Packages/GetPackages?page=1&pageSize=10' \
  -H 'X-Merchant-Id: <your merchant id>' \
  -H 'X-Api-Key: <your api key>'

Buying an eSIM

What happens when you call POST /api/Purchase/Buy.

Topping up an eSIM

Adding data to an eSIM you have already sold, rather than issuing a new one.

Idempotency & retries

A purchase that times out on your side has usually still completed here — the eSIM was issued and your wallet was debited. The response just never made it back. Retrying blind buys a second eSIM and charges you again.

Send a clientReference on every Buy and TopUp and that stops being a problem. It is your own id for the order — unique per order on your side. If a request carrying one you have used before arrives, the original order is returned instead of a new one being placed.

Fulfilment

Plans differ in how quickly a profile is issued and how much the network reports back afterwards. You never choose this — it is a property of the package — but it changes what GET /api/Order/GetOrderDetails can tell you, so handle both cases.

Merchant Wallet

Your company holds one wallet. Every purchase debits it by the cost price — what Mobisim charges you — not the retail price you resell at. A purchase is refused outright if the balance will not cover it, so keep an eye on the balance before a large batch.

Webhooks

Instead of polling, give us a URL and we POST a signed JSON event to it the moment something happens: an eSIM profile is ready, a top-up lands, a refund is credited, your wallet runs low. Events cover every order on your account, whether placed through this API or the Partner Portal.

Events

esim.installed, esim.activated, esim.usage_threshold, esim.expiring, catalog.updated and catalog.price_scheduled are delivered only to an endpoint that names them — an endpoint set to receive “all events” does not get these six. Tick them on the Developers page when you want them.

Request

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: MobiSIM-Webhooks/1.0
X-MobiSim-Event-Id: evt_4f1c2b9a0e5d4c7fa3b8e6d2c1a09f7e
X-MobiSim-Event-Type: order.completed
X-MobiSim-Timestamp: 1789466400
X-MobiSim-Signature: v1=5b2e0c…

{
  "id": "evt_4f1c2b9a0e5d4c7fa3b8e6d2c1a09f7e",
  "type": "order.completed",
  "createdAt": "2026-09-13T10:00:00Z",
  "data": {
    "orderId": "ACME-your-reference-123",
    "packageId": 1842,
    "packageTitle": "Europe 10GB 30 days",
    "iccid": "8944500000000000000",
    "activationCode": "LPA:1$smdp.example.com$ABCD-1234",
    "iosInstallLink": null,
    "androidInstallLink": null,
    "apn": "internet"
  }
}

Verifying signatures

Compute HMAC-SHA256 over {X-MobiSim-Timestamp}.{raw body} using the whole signing secret as the key, hex-encode it, and compare it with the X-MobiSim-Signature header after v1=. Use the raw bytes you received — re-serialising parsed JSON changes them.

// Node.js (Express): app.post("/webhooks/mobisim", express.raw({ type: "application/json" }), handler)
import crypto from "node:crypto";

function verify(req, secret) {
  const timestamp = req.header("X-MobiSim-Timestamp");
  const signature = req.header("X-MobiSim-Signature") ?? "";

  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = "v1=" + crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${req.body.toString("utf8")}`)
    .digest("hex");

  return signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

# Python
import hmac, hashlib, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-MobiSim-Timestamp"]
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = "v1=" + hmac.new(
        secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, headers.get("X-MobiSim-Signature", ""))

Retries and ordering

Errors

Failures come back in the same envelope as everything else, with success: false, a human-readable message, and data: null.

API Reference

Browse all available endpoints organised by resource.