Skip to main content
OnArrival

Build your travel integration with the OnArrival API.

See code samples, booking flows and how errors are handled. Request sandbox access to try the integration, then confirm what your production setup needs.

In short

Four steps to a working integration.

Every OnArrival integration does the same four things, in this order.

  1. 01Get test keysRequest sandbox access. You test against test inventory, so nothing real is booked.Request access
  2. 02SearchOne call asks every connected supplier and returns offers in one format.See the quickstart
  3. 03BookPrice the offer, add extras like trip cover, and take one payment.See the recipes
  4. 04Handle changesWebhooks tell your system when a booking changes. Safe retries mean a repeat never books twice.See errors and retries
Quickstart

Search a flight in ~12 lines.

Stays, ground, activities and Travel Fintech work the same way. Learn how to authenticate and how an offer looks once. Neither changes between products.

Install
npm i @onarrival/sdk
One SDK · every product
SDKoneflightsstaysgroundactivitiesfintechpayments
flights-quickstart.ts
import { OnArrival } from '@onarrival/sdk';

const client = new OnArrival({
  apiKey: process.env.ONARRIVAL_KEY,
  env: 'sandbox',
});

// Search across every connected supplier
const offers = await client.flights.search({
  from: 'BLR', to: 'LIS',
  depart: '2027-03-12',
  cabin: 'economy',
  pax: { adults: 1 },
});
Recipes

Build something real.

Use these examples to plan your integration. Confirm the supported calls and supplier conditions in the API reference.

01

Sell a flight + insurance bundle in one checkout

Search live flights, price cancel-for-any-reason (CFAR) cover for the exact flight, and take one payment for both. One booking comes back.

flights.searchbundles.createfintech.quotepayments.capture
02

Rebook a disrupted passenger automatically

Listen for schedule changes and cancellations, then swap the affected flight for the best protected alternative within your own service commitment (SLA). No human agent in the loop.

disruption.subscribeflights.exchangewebhooks.deliver
03

Settle multi-currency payouts to suppliers

Charge the traveller in their own currency, lock the exchange rate at booking, and reconcile each supplier payment to the cent in a double-entry ledger you can export nightly.

payments.capturefx.lockledger.settlewarehouse.sync
04

Embed a full trip: air, stay and ground

Flights, stays and transfers share one offer format, so you can search all three at once and build the trip. The themed React checkout drops straight in.

flights.searchstays.searchground.searchbundles.create
Errors & idempotency

How the SDK handles the hard parts.

Sometimes a supplier drops the connection in the middle of a booking. What happens next matters most. You get one error format, safe retries on every change, and failures you can rehearse in the sandbox.

502 · the one error object
retryable
{
  "error": {
    "code": "supplier_connection_dropped",
    "primitive": "flights",
    "message": "Supplier closed the session before capture confirmed.",
    "retryable": true,
    "retry_after_ms": 1200,
    "idempotency_key": "ik_8f2c1a90b4e7",
    "booking_state": "pending",
    "request_id": "req_01HX9Z4ABCDEF",
    "docs": "https://www.onarrival.com/docs"
  }
}
01

Idempotency keys

Every call that changes something takes a unique key. Retry after a timeout and you get the original result back: never a second booking, never a double charge. Keys are kept for 24 hours.

02

Typed errors

One error format across flights, stays, ground, activities and fintech. Same fields, same codes, same retryable flag, so you write your error handling once.

03

Webhook replay

Missed an update during a deploy? Resend any event, or a range, from the dashboard or API. Events are signed, in order and deduplicated by ID, so each is processed exactly once.

04

Sandbox parity

Trigger failures on demand with special test inputs: dropped sessions, slow suppliers, declined cards, schedule changes. The errors you handle in sandbox are the ones you get in production.

Full error reference
CLIENTik_8f2cdroppedretry · same keyorder×1ledger
In plain words

Think of the idempotency key as a receipt number for a request.

If a connection drops and you send the same request again with the same idempotency_key, the capture resolves once. The second request returns the first result, not a second booking. The fields are the same on every product.

Reference

What's in the docs.

These are the sections the full API reference covers. Request sandbox credentials to test the examples.

Illustration: two builders at a workbench assemble a miniature travel network of a paper plane, a model train and a small hotel, one placing the last piece while the other reads an open manual.
Get started
Quickstart
Set up credentials and make your first test booking.
Authentication
API keys, OAuth sign-in for embedded partners, and access scoped to each customer.
Sandbox vs production
How sandbox supplier inventory works, and the path to going live.
Products
Flights API
Shop, offer, book, exchange, refund across NDC, GDS and LCC.
Hotels API
Hotels, apartments and serviced stays, with duplicates merged and best rates.
Buses API
Intercity bus routes, seat selection and operator booking flows.
Experiences API
Tours, attraction tickets and activities, with product-specific confirmation terms.
Travel Fintech API
Eligible trip protection, policy binding and claims workflows.
Payments & ledger
Take payments, settle with suppliers, lock exchange rates and issue virtual cards.
Embedded
React SDK
Drop-in components themed to your design system.
React Native
Native checkout for iOS and Android, sharing one backend.
Web components
Framework-agnostic embeds for non-React stacks.
Operate
Webhooks
Booking events with signed delivery, retries and replay support.
Warehouse sync
Stream events to BigQuery, Snowflake, Redshift, or your own S3.
Disruption hooks
Schedule changes, cancellations and rebooks as code.
Trust
SOC 2 Type II
Annual report, available under NDA.
GDPR + DPA
A data processing agreement per customer, tools for data access requests and a list of sub-processors.
Customer-managed keys
Bring your own encryption keys (BYOK) on the Enterprise tier, with key-rotation hooks.
Start building
Request sandbox access for your travel integration.

Related reading

All field notes →
Technical architecture · 11 min

Travel API architecture needs orders, state and recovery

Supplier adapters handle API calls. A travel platform also needs a shared booking record, permission checks and recovery when a supplier response is late or unclear.

Pawan ShettyTechnical architecture · 11 min

Why a travel cart needs more than one checkout call

Flights, hotels and activities can expire or fail independently during checkout. A travel cart needs price checks, booking recovery and a payment plan for partial success.

Manan Vaghasiya