Official client for the OpenRoam Partner API: eSIMs, airtime, utility payments, gift cards, hotels and flights. Ruby 3.0+.
gem install openroam -v 0.1.0-rc.6or in your Gemfile: gem 'openroam', '0.1.0-rc.6'.
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.
require 'openroam'
openroam = OpenRoam::Client.new(ENV.fetch('OPENROAM_API_KEY')) # or OpenRoam::Client.new with OPENROAM_API_KEY set
found = openroam.esims.search(country_code: 'JP')
quote = openroam.esims.quote(currency: 'USD', items: items)
order = openroam.esims.order(currency: 'USD', items: items)
openroam.esims.get_usage(iccid)
openroam.orders.get(order_id)Every product is a method of the client: esims, airtime, utilities, gift_cards, hotels, flights, plus orders, order_items,
wallets, currencies, countries and mobile_networks. 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:
openroam.order_items.get_amendment(item_id, amendment_id). - Query parameters are keyword arguments in snake_case:
openroam.orders.list(page: 2, product_types: %w[esim giftCard]). Times are sent as ISO 8601, symbols as strings, and an unknown keyword is anArgumentError. - A body is passed as it is, with the API's field names: keywords as above, a Hash (
openroam.esims.quote(body)) or a model (OpenRoam::EsimOrderRequest.new(...)). It is never wrapped in an object named after its type. - Answers are models:
found.items,found.pagination.
Options when you need them:
openroam = OpenRoam::Client.new(
api_key: 'key',
environment: :sandbox, # default :production
max_retries: 3 # default 0: no retries
# base_url: 'https://...' to point anywhere else, for example a development host
)A block receives the OpenRoam::Configuration before the first request, for anything else (timeout, logging, a Faraday adapter):
openroam = OpenRoam::Client.new('key') { |config| config.timeout = 30 }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:
openroam.esims.order(body, idempotency_key: my_order_id)A failed call raises an OpenRoam::Error (a StandardError) with the error body of the API: status, code (an Integer, branch on this),
error_name (for example PRICE_ABOVE_LIMIT), message, request_id (keep it for support) and details. When no answer arrived
(network error, timeout), status is nil and cause has the original error.
begin
openroam.esims.order(body)
rescue OpenRoam::Error => e
raise unless e.code == 11002 # the price rose above your maxPrice
# ...
endPagination depends on the method. esims.search accepts page: and limit: and returns items and pagination, while orders.list returns orders and pagination.
esims.list_catalog accepts cursor: and limit: and returns items and next_cursor; pass next_cursor as cursor: to fetch the next page.
Some lists, such as esims.list_compatible_devices, return an unpaged array.
OpenRoam.verify_webhook(
secret: ENV.fetch('OPENROAM_WEBHOOK_SECRET'),
timestamp: request.headers['X-OpenRoam-Timestamp'],
event_id: request.headers['X-OpenRoam-Event-Id'],
signature: request.headers['X-OpenRoam-Signature'],
raw_body: request.raw_post # the body exactly as received, before JSON parsing
) # raises OpenRoam::WebhookSignatureError when invalid or older than 5 minutesRetries are off by default. Set max_retries: to retry network errors, 429, 502/503/504 and "still running" (12002) safely:
a POST is sent again only with its Idempotency-Key, the same key and the same body, and order always has one.
openroam = OpenRoam::Client.new(api_key: key, max_retries: 3)The full behaviour: Retries and idempotency. OpenRoam::Retry.apply and OpenRoam.new_idempotency_key
are also available 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.