Official client for the OpenRoam Partner API: eSIMs, airtime, utility payments, gift cards, hotels and flights.
.NET 8+ (net8.0).
dotnet add package OpenRoam --version 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.
using OpenRoam;
using OpenRoam.Model;
using var openroam = new OpenRoamClient(Environment.GetEnvironmentVariable("OPENROAM_API_KEY")); // or new OpenRoamClient() with OPENROAM_API_KEY set
var found = await openroam.Esims.SearchAsync(new EsimsSearchQuery { CountryCode = "JP" });
var request = new EsimOrderRequest(currency: "USD", items: items);
var quote = await openroam.Esims.QuoteAsync(request);
var order = await openroam.Esims.OrderAsync(request);
await openroam.Esims.GetUsageAsync(iccid);
await openroam.Hotels.SearchAsync(new HotelSearchRequest(/* ... */));Every product is a property of the client: Esims, Airtime, Utilities, GiftCards, Hotels, Flights,
plus Orders, OrderItems (with OrderItems.ManualAmendments), Wallets, Currencies, Countries and MobileNetworks. Buying always reads SearchAsync, QuoteAsync,
OrderAsync; GetAsync fetches one thing you own, List...Async returns many, everything else starts with a verb. A path id is the first
argument, a body is passed as it is (the request model), query parameters are one object such as EsimsSearchQuery, and every method takes a
CancellationToken last.
Make one client and keep it (it holds the HTTP connections); it is safe to share between threads. Options when you need them:
using var openroam = new OpenRoamClient(new OpenRoamOptions
{
ApiKey = "key",
Environment = OpenRoamEnvironment.Sandbox, // default Production
MaxRetries = 3, // default 0: no retries
// BaseUrl = "https://...", to point anywhere else, for example a development host
// HttpClient = httpClientFactory.CreateClient("openroam"), to send the requests through your own HttpClient
});An idempotency key means: if the same request arrives twice, OpenRoam makes one order, not two. OrderAsync 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.OrderAsync(request, new OrderRequestOptions { IdempotencyKey = myOrderId });A failed call throws an OpenRoamException with the error body of the API: Status, Code (branch on this), ErrorName, Message,
RequestId (keep it for support) and Details. When no answer arrived (network error, timeout), Status is null and InnerException has
the original error. A cancellation you asked for stays an OperationCanceledException.
try
{
await openroam.Esims.OrderAsync(request);
}
catch (OpenRoamException error) when (error.Code == 11002)
{
// the price rose above your maxPrice
}Pagination depends on the method. Esims.SearchAsync accepts Page and Limit and returns Items and Pagination, while
Orders.ListAsync returns Orders and Pagination. Esims.ListCatalogAsync accepts Cursor and Limit and returns Items and
NextCursor; pass NextCursor as Cursor to fetch the next page. Some lists, such as Esims.ListCompatibleDevicesAsync, return an unpaged list.
OpenRoamWebhooks.Verify(secret, timestampHeader, eventIdHeader, signatureHeader, rawBody);
// throws WebhookSignatureException when invalid or older than 5 minutesRetries are off by default. Set MaxRetries to retry network errors, 429, 502/503/504 and "still running" (12002) safely:
a POST with an Idempotency-Key (OrderAsync always has one) is sent again with the same key and the same body; a POST without one,
such as QuoteAsync, is sent again only after a 429, which the API refused before doing anything. Never after a 500.
using var openroam = new OpenRoamClient(new OpenRoamOptions { ApiKey = apiKey, MaxRetries = 3 });Each call is limited to 100 seconds, waits between retries included. The full behaviour: Retries and idempotency.
RetryHandler (a DelegatingHandler) and OpenRoamRetry.NewIdempotencyKey() are also public 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, Retries and the errors are
hand-written. MIT licensed.