Official client for the OpenRoam Partner API: eSIMs, airtime, utility payments, gift cards, hotels and flights. For servers and tools (never ship your API key inside a mobile or web app).
dart pub add openroam:0.1.0-rc.6This is a release candidate: install it by its exact version, as above; a plain install does not pick it up. Before 1.0 the API can change between minor versions; every change is listed in the changelog.
import 'package:openroam/openroam.dart';
final openroam = OpenRoam('your-key'); // or OpenRoam.fromEnvironment() with OPENROAM_API_KEY set
final found = await openroam.esims.search(countryCode: 'JP');
final body = EsimOrderRequest(currency: 'USD', items: [EsimOrderRequestItem(publicId: offerId)]);
final quote = await openroam.esims.quote(body);
final order = await openroam.esims.order(body);
await openroam.esims.getUsage(iccid);
openroam.close(); // when you no longer need the clientEvery product is a field of the client: esims, airtime, utilities, giftCards, hotels, flights, plus orders, orderItems,
wallets, currencies, countries and mobileNetworks. Buying always reads search, quote, order; get fetches one thing you own,
list... returns many, everything else starts with a verb. A path id is the first argument, a body (the request model itself) the next one,
and query parameters are named arguments. A body the API does not require is nullable: pass null to send none.
Options when you need them:
final openroam = OpenRoam(
'your-key',
environment: OpenRoamEnvironment.sandbox, // default OpenRoamEnvironment.production
maxRetries: 3, // default 0: no retries
// baseUrl: 'https://...' to point anywhere else, for example a development host
// httpClient: your own http.Client
);OpenRoam.fromEnvironment(...) takes the same options and reads the key from OPENROAM_API_KEY.
An idempotency key means: if the same request arrives twice, OpenRoam makes one order, not two. order() creates a key for you on every call.
To stay safe even if your own program crashes and asks again, pass a UUID generated once and persisted for that purchase, for example your order id if it is a UUID:
await openroam.esims.order(body, idempotencyKey: myOrderId);A failed call throws an OpenRoamException with the error body of the API: status, code (branch on this), errorName (the API's name,
for example PRICE_ABOVE_LIMIT), message, requestId (keep it for support) and details. When no answer arrived (network error), status
is null and cause has the original error. A call stopped through its abortTrigger throws the RequestAbortedException of package:http.
try {
await openroam.esims.order(body);
} on OpenRoamException catch (error) {
if (error.code == 11002) { /* the price rose above your maxPrice */ }
else rethrow;
}Pagination depends on the method. esims.search takes page and limit and returns items and pagination, while orders.list returns
orders and pagination. esims.listCatalog takes cursor and limit and returns items and nextCursor; pass nextCursor as cursor
to fetch the next page. Some lists, such as esims.listCompatibleDevices, return an unpaged List.
verifyWebhook(
secret: secret,
timestamp: headers['x-openroam-timestamp']!,
eventId: headers['x-openroam-event-id']!,
signature: headers['x-openroam-signature']!,
rawBody: rawBody, // exactly as received
); // throws WebhookSignatureException when invalid or older than 5 minutesAn order item (and a webhook item, and an item of an order request) holds one product variant, chosen by productType. Read it with the getter for its product, which is null for the others:
for (final item in order.items) {
final esim = item.esim;
if (esim != null) print(esim.fulfillment); // eSIM details are kept
}The variants are airtime, esim, flight, giftCard, hotel and utility; item.value is the variant itself. An unknown productType throws a FormatException, never a silent gap.
Retries are off by default. Set maxRetries to retry network errors, 429 and 502/503/504 with backoff, and to wait for a purchase that is
still running (12002). A POST is sent again only with its Idempotency-Key, the same key and the same body, and order() always has one;
a 500 never is.
final openroam = OpenRoam(apiKey, maxRetries: 3);The full behaviour: Retries and idempotency. RetryingClient, RetryOptions and newIdempotencyKey
are also exported if you build your own requests.
-
Amounts are
{ amount, currency }.priceis what OpenRoam charges you,valuewhat your customer receives. - Full API documentation: https://openroam.com (partner portal). Support: support@openroam.com.
The client is generated from the OpenRoam Partner API description, so it always matches the API; webhooks, retry and the errors are hand-written. MIT licensed.