openroam 0.1.0-rc.1
openroam: ^0.1.0-rc.1 copied to clipboard
Official OpenRoam Partner API client: eSIMs, airtime, utility payments, gift cards, hotels and flights.
OpenRoam SDK for Dart #
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).
Install #
dart pub add openroam:0.1.0-rc.1
This 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.
Quick start #
import 'package:openroam/api.dart';
import 'package:openroam/webhooks.dart';
final client = ApiClient(
basePath: openRoamSandboxUrl, // or openRoamProductionUrl
authentication: ApiKeyAuth('header', 'X-Partner-Key')..apiKey = apiKey,
);
final result = await EsimsApi(client).esimsSearch(countryCode: 'JP');
Every product has its own class (AirtimeApi, EsimsApi, GiftCardsApi, HotelsApi, FlightsApi, UtilityApi, OrdersApi, WalletsApi...) and each follows search, quote, order.
Webhooks #
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 minutes
Order items and webhook items #
An 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.
Good to know #
- Orders need an
Idempotency-Key(a new UUID per purchase). After a timeout or a5xx, retry with the same key and the same body: it never charges twice. - Amounts are
{ amount, currency }.priceis what OpenRoam charges you,valuewhat your customer receives. - Errors carry
code,name,message,requestIdanddetails; quoterequestIdwhen you contact support. - Full API documentation: https://openroam.com (partner portal). Support: support@openroam.com.
This SDK is generated from the OpenRoam Partner API description; webhooks is hand-written. MIT licensed.