Movmo Express Checkout Button

A React component for integrating Movmo's Express Checkout functionality into airline websites.

Installation

npm install @movmo/express-checkout-button

or

yarn add @movmo/express-checkout-button

Usage

Basic Example with Pre-saved Offer

If you have already saved the flight offer to Movmo's system and have an offer ID:

import React from 'react';
import { MovmoCheckoutButton } from '@movmo/express-checkout-button';
// Important: Import the styles
import '@movmo/express-checkout-button/dist/index.css';

function MyBookingPage() {
  return (
    <div className="booking-page">
      <h1>Complete your booking</h1>

      <MovmoCheckoutButton
        iataCode="PR"
        apiKey="your-movmo-api-key"
        providerID="amadeus"
        flightOfferID="offer-123-456-789"
        isProd={false} // Set to true for production environment
      />
    </div>
  );
}

export default MyBookingPage;

Example with Raw Flight Offer

If you have the raw flight offer data that needs to be saved when the button is clicked:

import React from 'react';
import { MovmoCheckoutButton } from '@movmo/express-checkout-button';
// Important: Import the styles
import '@movmo/express-checkout-button/dist/index.css';

function MyBookingPage() {
  // Flight offer data retrieved from your booking system (Amadeus, Sabre, etc.)
  const flightOffer = {
    // Your raw flight offer data from the provider
  };

  return (
    <div className="booking-page">
      <h1>Complete your booking</h1>

      <MovmoCheckoutButton
        iataCode="AA"
        apiKey="your-movmo-api-key"
        providerID="sabre"
        flightOffer={flightOffer}
        isProd={false} // Set to true for production environment
      />
    </div>
  );
}

export default MyBookingPage;

Props

| Prop | Type | Required | Description | | --------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | iataCode | string | Yes | The IATA code for the airline | | apiKey | string | Yes | Your Movmo API key | | providerID | string | Yes | The provider identifier (e.g., "amadeus", "sabre", "duffel") | | flightOffer | object | No* | The raw flight offer data object from the provider. Required if flightOfferID is not provided | | flightOfferID | string | No* | The ID of a pre-saved flight offer. Required if flightOffer is not provided | | isProd | boolean | No | Whether to use production endpoints (default: false). When true, uses production API and flights URLs; when false, uses e2e (testing) endpoints | | className | string | No | Extra CSS classes merged onto the button element | | onExit | function| No | (info: MovmoCheckoutExitInfo) => void — called when the checkout overlay hands control back to your page. info.reason is 'booking_confirmed' (traveler clicked "Return to airline" after a successful booking — a booking-complete callback already fired for it), 'offer_unavailable' (the offer expired/became unbookable), or 'search_again' |

*Note: Either flightOffer or flightOfferID must be provided, but not both.

Provider Options

The providerID prop accepts provider identifiers as strings. Common providers include:

// Common provider IDs
'amadeus'; // For Amadeus flight data
'sabre'; // For Sabre flight data
'duffel'; // For Duffel flight data
// ... and other supported providers

Environment Configuration

The isProd prop controls which Movmo endpoints are used:

• When isProd={false} (default):

  • API endpoint: https://e2e.api.movmo.io
  • Flights UI: https://flights.e2e.movmo.io

• When isProd={true}:

  • API endpoint: https://api.movmo.io
  • Flights UI: https://flights.movmo.io

Vanilla JS / <script> tag (no React required)

The package also ships a self-contained UMD bundle (dist/express-checkout.umd.js, exposed via the package's unpkg field) for host pages without React or a bundler. It defines window.MovmoExpressCheckout:

<div id="movmo-checkout"></div>
<!-- Production: pin an exact version and add Subresource Integrity so a CDN compromise
     can't alter the script (generate the hash from the pinned file, e.g.
     `openssl dgst -sha384 -binary express-checkout.umd.js | openssl base64 -A`): -->
<script
  src="https://unpkg.com/@movmo/[email protected]/dist/express-checkout.umd.js"
  integrity="sha384-<hash-of-the-pinned-file>"
  crossorigin="anonymous"
></script>
<script>
  var handle = window.MovmoExpressCheckout.mount('#movmo-checkout', {
    iataCode: 'AA',
    apiKey: 'your-movmo-api-key',
    providerID: 'sabre',
    flightOffer: rawOffer,
    // isProd: true — add when you go live
  });
  // handle.unmount() removes the button; window.MovmoExpressCheckout.version reports the SDK version
</script>

mount(target, options) accepts a CSS selector or an Element (it throws a clear error when a selector matches nothing) and takes the same options as the React component's props. React, styling, and all dependencies are bundled — nothing else to include.

Internal / QA traffic flagging

When the host page URL carries ?mv_internal=1, the button flags its own analytics events as internal traffic and appends mv_internal=1 to the checkout URL, so the entire embedded session (button + Movmo checkout iframe) is excluded from partner-facing KPIs. Use it on demo, QA, and test pages; it is sticky per tab and entirely fail-open.

Analytics (scoped)

MovmoCheckoutButton self-instruments the pre-iframe funnel — from the button rendering on the airline page through the traveler landing inside the Movmo checkout — using @movmo_app/analytics in scoped mode. Scoped mode disables every document-level listener the SDK would otherwise install (click/rage-click/hover/scroll/field/section autocapture); the button only ever attaches listeners to its own DOM node and the checkout overlay it creates. It never observes the partner's page, reads partner form fields, or inspects anything outside those two elements. The airline identifier passed as iataCode becomes partner_id, and the partner page's hostname is the only page context transmitted — never the path, full URL, referrer, page content, or DOM structure.

Ten events cover the funnel:

| Event | Fires when | | ------------------------------ | ------------------------------------------------------------------------ | | plugin_loaded | The button mounts and the scoped tracker initializes | | button_viewed | The button crosses 50% viewport visibility (once per mount) | | button_hovered | The pointer leaves the button after a ≥200ms hover | | button_clicked | The button is clicked | | offer_save_started | A raw flight offer begins saving (no pre-saved flightOfferID) | | offer_save_succeeded | The offer save call returns an offer ID | | offer_save_failed | The offer save call returns no offer ID (previously a silent no-op) | | overlay_opened | The checkout overlay iframe is created | | iframe_ready | The embedded flights-ui document sends its first MOVMO_READY handshake | | overlay_abandoned_pre_iframe | The overlay is torn down before MOVMO_READY was ever seen |

iframe_ready and overlay_abandoned_pre_iframe are mutually exclusive per overlay open — whichever happens first wins, and neither fires again until the overlay is reopened. Both carry a ms_since_open property so you can track how long the iframe took to load or how quickly a traveler bounced.

Every tracking call is fail-open: analytics never throws, and a network or init failure never blocks or delays checkout.

Configuration:

• The analytics ingest endpoint defaults to https://api.movmo.io/v1/t (prod) / https://e2e.api.movmo.io/v1/t (e2e), selected by the same isProd prop as the checkout URL. Override it with REACT_APP_MOVMO_ANALYTICS_URL (inlined at build time), the same mechanism as REACT_APP_MOVMO_CHECKOUT_URL.
• On click, the button appends an mvs (Movmo session) query param to the checkout URL with its current analytics session id. The embedded flights-ui SDK adopts that id on load, so button_viewed → … → booking_confirmed all land in one session instead of two.

CSS Integration

You must import the component's CSS for proper styling:

// Import the styles
import '@movmo/express-checkout-button/dist/index.css';

Every class the package emits is namespaced with a movmo- prefix (for example .movmo-px-7, .focus\:movmo-ring-2) as of 1.11.0, so the stylesheet cannot collide with your page's own Tailwind or utility CSS — and vice versa. This applies to the <script> tag build too, which injects the same stylesheet into your page. The className prop is passed through untouched: your own classes are never prefixed.

If you previously styled the button by targeting one of its internal class names (for example .bg-gradient-normal), switch to a descendant selector on your own wrapper — .my-wrapper button for the button, .my-wrapper button > span for the Movmo badge — which is stable across versions.

The package has no runtime HTTP dependency: the offer-save call uses the platform fetch. If your project relied on the transitive axios install that older versions pulled in, declare it yourself.

Development

Running Storybook

To run the component in a local development environment with interactive documentation:

# Install dependencies
npm install

# Start Storybook
npm run storybook

This will launch Storybook at http://localhost:6006 where you can explore and interact with the component.

Building the Component

npm run build

Storybook Examples

The Storybook includes several examples:

1. With Pre-saved Offer ID: Example using a pre-saved flight offer ID
2. With Raw Flight Offer: Example with raw Amadeus flight offer data that will be saved on button click
3. Production Environment: Example configured for production environment
4. Minimal With Offer ID: Minimal configuration example with just the required props

License

MIT