roamgoDevelopers
OpenAPIPartner panel
Partner API · v1

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.

Make your first request Create an API key
Production base URLhttps://api.roamgo.net/api/partner/v1
01Quick 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.

1

Create a key

Open API keys in the partner panel, choose test mode and copy the key ID and secret. The secret is shown once.

2

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.

3

Place an order

Fetch a plan ID, then send POST /orders with an idempotency key. Fulfillment completes asynchronously.

4

Listen for fulfillment

Register a webhook and handle order.fulfilled to receive the activation details as soon as they are ready.

02Authentication

HMAC-signed on every request

Every call uses a public key ID and a signature derived from the secret. Requests outside the five-minute timestamp window are rejected.

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.ROAMGO_KEY_ID;
const SECRET = process.env.ROAMGO_SECRET;

async function roamgoFetch(method, path, body) {
  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${path}\n${bodyHash}`;
  const sig = crypto.createHmac("sha256", SECRET).update(canonical).digest("hex");

  const response = await fetch("https://api.roamgo.net/api/partner/v1" + path, {
    method,
    headers: {
      Authorization: `Roamgo-HMAC-SHA256 keyId=${KEY_ID}, ts=${ts}, sig=${sig}`,
      ...(raw && { "Content-Type": "application/json" }),
    },
    body: raw || undefined,
  });
  return response.json();
}
Server-side onlyKeep API secrets in an encrypted secrets manager and generate signatures in your backend.
03Environments

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.

04API reference

Endpoints

All responses use JSON except QR images and invoice PDFs. Select any endpoint to update the request example.

Account

1 endpoints

Catalog

2 endpoints

Orders

5 endpoints

eSIMs

4 endpoints

Credit

2 endpoints

Webhooks

6 endpoints
05Webhooks

React to lifecycle events

Verify X-Roamgo-Signature against the raw request body, acknowledge within 10 seconds, and deduplicate on X-Roamgo-Event-Id.

order.createdorder.provisioningorder.fulfilledorder.failedorder.refundedesim.activatedesim.depletedesim.expiredcredit.lowtopup.completedtopup.failed
06Errors & 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.

422validation_failedFix the request before retrying.
401signature_invalidCheck signing input, secret, and clock.
402insufficient_creditAdd partner credit, then retry.
403forbiddenUse a key with the required scope.
409idempotency_conflictUse a fresh idempotency key.
429rate_limitedWait for Retry-After.