@movmo/express-checkout-button

@movmo/express-checkout-button is a React component that embeds the Movmo Express Checkout flow as a “Buy with Movmo” button on a partner page. When the user clicks it, the component persists the selected flight offer to Movmo and opens the Movmo checkout SPA in a full-screen iframe over the partner page. Payment, passenger collection, and the airline booking call all happen inside the iframe — the partner page stays in control of the surrounding URL.

Current version	1.2.1
Peer dependencies	React 16.8+ (16.8 / 17 / 18 supported)
License	MIT
npm	@movmo/express-checkout-button

Install

npm install @movmo/express-checkout-button

Import the package stylesheet once at app boot:

import "@movmo/express-checkout-button/dist/index.css";

The CSS does not include Tailwind’s preflight reset, so it will not interfere with your existing styles. It imports the Inter font from Google Fonts; override font-family if you serve fonts locally.

Mount the button

import { MovmoCheckoutButton } from "@movmo/express-checkout-button";

<MovmoCheckoutButton
  iataCode="PR"
  apiKey={process.env.REACT_APP_MOVMO_API_KEY}
  providerID="amadeus"
  flightOffer={selectedOffer}
  isProd={false}
/>;

On click, the component:

1. Saves the offer to Movmo via createProviderOffer (POST /v1/flights/providers/{provider}/offers) — skipped if you pass a pre-saved flightOfferID instead of a raw flightOffer.
2. Pushes a /movmo/checkout URL onto window.history so the partner page can route around the iframe.
3. Mounts a full-screen <iframe> pointing at https://flights.movmo.io/index.html#/booking?... (or https://flights.e2e.movmo.io/... when isProd is false).
4. Listens for a MOVMO_BOOKING_COMPLETE postMessage from the iframe origin and updates window.history to /movmo/checkout/booking/{bookingId} when the booking lands.

Props

Prop	Type	Required	Description
iataCode	string	yes	Your airline IATA code (e.g. "PR", "AA"). Sent to Movmo as movmo-customer-id.
apiKey	string	yes	Your Movmo API Gateway key. Sent as x-api-key. Provisioned at onboarding — see Authentication.
providerID	string	yes	The flight provider the offer came from. One of: amadeus, sabre, duffel, darwin, dohop.
flightOffer	object	conditional	The raw flight offer object from your provider. Required if flightOfferID is not set.
flightOfferID	string	conditional	The Movmo offer UUID returned by a prior createProviderOffer call. Required if flightOffer is not set.
isProd	boolean	no	true targets flights.movmo.io and api.movmo.io; false (default) targets flights.e2e.movmo.io and e2e.api.movmo.io.
className	string	no	Appended to the button’s class list. Useful for w-full and similar layout tweaks.

Exactly one of flightOffer or flightOfferID must be set. The two props are mutually exclusive: pass the raw offer if you have not persisted it yet, or the saved offer ID if you already have.

Two usage modes

Raw offer (most common)

The partner page already has the user’s selected offer (e.g. from an Amadeus search response). Pass the raw object — the component persists it on click:

<MovmoCheckoutButton
  iataCode="PR"
  apiKey={process.env.REACT_APP_MOVMO_API_KEY}
  providerID="amadeus"
  flightOffer={{
    offer: amadeusOffer,
    dictionaries: amadeusDictionaries,
  }}
/>

The component sends the object as-is to createProviderOffer. Movmo’s backend understands each provider’s native shape — no client-side normalization is required.

Pre-saved offer ID

The partner has already saved the offer to Movmo (for example, after a server-side search) and only needs to launch checkout:

<MovmoCheckoutButton
  iataCode="PR"
  apiKey={process.env.REACT_APP_MOVMO_API_KEY}
  providerID="amadeus"
  flightOfferID="33333333-3333-3333-3333-333333333333"
/>

No persistence call is made — the iframe loads immediately.

Iframe lifecycle and postMessage

Once mounted, the iframe overlay is full-screen (position: fixed, z-index: 9999). The Movmo checkout SPA inside handles passenger collection, payment-method selection, and the airline booking call.

On a successful booking, the iframe posts a message with this shape:

type MovmoBookingComplete = {
  type: "MOVMO_BOOKING_COMPLETE";
  bookingId: string;
  airlineRef: string;
  providerId: string;
};

The component listens only to messages from flights.movmo.io (or flights.e2e.movmo.io in pre-prod) and pushes /movmo/checkout/booking/{bookingId} onto the partner page’s history. If you want to redirect to your own confirmation page or fire analytics, listen to the same message on your end and intercept it before the component’s listener runs.

Underlying REST operation

The SDK calls one OpenAPI operation in raw-offer mode:

Operation	Path
createProviderOffer	POST /v1/flights/providers/{provider}/offers

In flightOfferID mode, no REST call is made from the partner page — the iframe handles all subsequent calls itself. Full schemas in the OpenAPI spec under tags: [Flights].