Build global eSIM into your product. Browse live reseller pricing, place orders, deliver activation details, reconcile credit, and respond to fulfillment events from one server-to-server API.
https://api.todomobile.mobi/api/partner/v1
01 Quick start
From key to first order Use a test key while integrating. Test orders preserve the live response shape without provisioning an eSIM or debiting credit.
Create a key Open API keys in the partner panel, choose test mode, optionally restrict source IPs, and copy the key ID and secret. The secret is shown once.
Sign requests Sign the timestamp, HTTP method, path with query, and SHA-256 body hash with HMAC-SHA256. Never expose the secret in frontend code.
Place an order Fetch a plan ID, then send POST /orders with an idempotency key. Fulfillment completes asynchronously.
Listen for fulfillment Register a webhook and handle order.fulfilled to receive the activation details as soon as they are ready.
02 Authentication
HMAC-signed on every request Every call uses a public key ID and a signature derived from the secret. Requests outside the two-minute timestamp window are rejected. Keys can also require an exact IPv4/IPv6 address or CIDR range configured in the partner panel.
Canonical string
{timestamp}\n{METHOD}\n{path-with-query}\n{sha256(raw-body)}Node.js signing helper
import crypto from "node:crypto";
const KEY_ID = process.env.API_KEY_ID;
const SECRET = process.env.API_SECRET;
async function apiFetch(method, path, body) {
const url = new URL("https://api.todomobile.mobi/api/partner/v1" + path);
url.searchParams.set("request", crypto.randomUUID());
const signedPath = url.pathname + url.search;
const raw = body ? JSON.stringify(body) : "";
const ts = Math.floor(Date.now() / 1000);
const bodyHash = crypto.createHash("sha256").update(raw).digest("hex");
const canonical = `${ts}\n${method}\n${signedPath}\n${bodyHash}`;
const sig = crypto.createHmac("sha256", SECRET).update(canonical).digest("hex");
const response = await fetch(url, {
method,
headers: {
Authorization: `HMAC-SHA256 keyId=${KEY_ID}, ts=${ts}, sig=${sig}`,
...(raw && { "Content-Type": "application/json" }),
},
body: raw || undefined,
});
return response.json();
}Server-side only Keep API secrets in an encrypted secrets manager and generate signatures in your backend.
03 Environments
Same API, safe test mode rk_test_… Test No supplier calls or credit debits. Returns synthetic ICCIDs for complete integration testing.
rk_live_… Live Provisions real eSIMs and debits the shared reseller-credit balance.
04 API reference
Endpoints All responses use JSON except QR images and invoice PDFs. Select any endpoint to update the request example.
Account 1 endpoints GET /meREAD
Account snapshot Read partner profile, credit balance, key mode, scope, and rate limits.
Show request example
Catalog 2 endpoints GET /plans?country=JP&minDays=7READ
List plans Browse active plans available to your reseller catalog with filters and pagination.
Show request example GET /plans/{id}READ
Get a plan Retrieve one plan and its grouped country and network coverage.
Show request example
Orders 5 endpoints POST /ordersORDERS
Create an order Debit partner credit and enqueue an eSIM order for asynchronous fulfillment.
Show request example GET /orders?page=1READ
List orders List your orders newest first, with status, email, reference, and date filters.
Show request example GET /orders/{id}READ
Get an order Read full order details, eSIM activation artifacts, and invoice metadata.
Show request example POST /orders/{id}/refundORDERS
Refund an order Refund a partner order idempotently and return the credit it debited. A delivered order refunds only once every eSIM on it is cancelled at its network, which works only while nobody has installed it; otherwise the answer is 409 order_not_refundable and no credit moves.
Show request example GET /orders/{id}/invoice.pdfREAD
Download invoice Stream the order invoice as a PDF document.
Show request example
eSIMs 4 endpoints GET /esims/{id}/qrREAD
Download QR code Render the activation profile as a PNG QR code.
Show request example POST /esims/{id}/reinstallORDERS
Transfer an eSIM to a new device Re-arm an eligible profile and return refreshed activation credentials. Some profiles cannot be transferred, and others can only be reinstalled on the original device. Profiles without reinstall support return a validation error.
Show request example GET /esims/{id}/topupsREAD
List top-ups List data add-ons priced for your partner account. To buy one, post its providerTopUpPlanId back; the same add-on keeps the same id.
Show request example POST /esims/{id}/topupsORDERS
Purchase a top-up Debit reseller credit and apply a selected data add-on to an existing eSIM. Status is COMPLETED, or PROCESSING when the network did not answer in time: it is then neither resent nor refunded until settled, and topup.completed or topup.failed follows.
Show request example
Credit 2 endpoints GET /credit/balanceREAD
Get balance Read the reseller wallet balance and configured low-credit threshold.
Show request example GET /credit/entriesREAD
List credit entries Reconcile credit and debit activity with cursor-based pagination.
Show request example
Webhooks 6 endpoints GET /webhooksREAD
List webhook endpoints List endpoint configuration without exposing signing secrets.
Show request example POST /webhooksFULL
Create a webhook endpoint Register a safe HTTPS destination and reveal its signing secret once.
Show request example POST /webhooks/{id}FULL
Update a webhook endpoint Change subscriptions, toggle delivery, rename, or rotate the signing secret.
Show request example DELETE /webhooks/{id}FULL
Delete a webhook endpoint Delete an endpoint and its delivery history permanently.
Show request example GET /webhooks/{id}/deliveriesREAD
List webhook deliveries Inspect delivery status, attempts, response codes, and retry scheduling.
Show request example POST /webhooks/{id}/deliveries/{deliveryId}/retryFULL
Retry a webhook delivery Re-queue an eligible delivery for the next worker cycle.
Show request example
AI Operator 1 endpoints POST /assistant/respondREAD
AI for your existing support system Send a bounded customer snapshot from your authenticated backend. Returns an answer, up to three validated cards when requested, and a handoff signal for your helpdesk. Live key and shared AI allowance required. No provider credentials, account mutations or message delivery. Integration guide: /docs/ai-operator.
Show request example 05 Webhooks
React to lifecycle events Verify X-Webhook-Signature against the raw request body, acknowledge within 10 seconds, and deduplicate on X-Webhook-Event-Id.
order.createdorder.provisioningorder.fulfilledorder.failedorder.refundedesim.activatedesim.depletedesim.expiredcredit.lowtopup.completedtopup.failed
06 Errors & rate limits
Stable errors, predictable retries Use the HTTP status as the source of truth and error.code for application logic. Every response includes rate-limit headers.
422 validation_failedFix the request before retrying.
401 signature_invalidCheck signing input, secret, and clock.
402 insufficient_creditAdd partner credit, then retry.
403 ip_not_allowedSend the request from an IP allowed for this key.
403 forbiddenUse a key with the required scope.
409 idempotency_conflictUse a fresh idempotency key.
429 rate_limitedWait for Retry-After.