Skip to main content

Inttegro for React

Use @inttegro/react to render Inttegro-hosted Checkout as a React component. The adapter loads and mounts Checkout, applies supported updates, forwards lifecycle events, and cleans up with the component tree.

Developer preview

This package and the hosted runtime are not yet available for live payments. The installation commands below will work after the preview package is published.

Prerequisites

  • React 18 or newer
  • A backend that creates and finalizes an Inttegro Order
  • The client-safe Order ID returned to your React application

Install the component

npm install @inttegro/react

Read the npm setup guide

Render Checkout

Pass the finalized Order ID to Checkout. Keep secret API keys and Order creation on your backend.

import { useState } from 'react'
import {
  Checkout,
  type CheckoutErrorEvent,
  type CheckoutEvent,
} from '@inttegro/react'

const appearance = { theme: 'system' } as const

function errorMessage(error: CheckoutErrorEvent | Error) {
  return error instanceof Error ? error.message : error.error.message
}

export function CheckoutPage({ orderId }: { orderId: string }) {
  const [message, setMessage] = useState('')

  function handleEvent(event: CheckoutEvent) {
    if (event.type === 'paymentAttempt') {
      setMessage('Starting your payment…')
    }
  }

  return (
    <>
      <Checkout
        appearance={appearance}
        locale="en-GH"
        orderId={orderId}
        title="Complete your payment"
        onCompleted={() => window.location.assign('/payment-status')}
        onError={(error) => setMessage(errorMessage(error))}
        onEvent={handleEvent}
      />
      <p aria-live="polite">{message}</p>
    </>
  )
}

The component also accepts className, style, and timeout. Changing appearance or locale updates the active Checkout. Changing orderId, timeout, or title destroys the old instance and creates a new one.

Handle lifecycle callbacks

PropCalled when
onCompletedCheckout observes payment completion.
onErrorLoading, mounting, or the hosted flow reports an error.
onEventAny privacy-safe lifecycle event is received.
onReadyCheckout is ready for customer interaction.

onError receives an Error for loader or mount failures and a CheckoutErrorEvent for errors reported by the hosted flow. onEvent receives every hosted lifecycle event, including ready, completed, and error.

Use these callbacks for interface state and telemetry. A completed callback is not fulfillment authority; have your backend look up the Order before releasing goods or granting access.

Focus or update Checkout

The forwarded ref exposes focus() and update():

import { useRef } from 'react'
import { Checkout, type CheckoutHandle } from '@inttegro/react'

export function FocusedCheckout({ orderId }: { orderId: string }) {
  const checkout = useRef<CheckoutHandle>(null)

  return (
    <Checkout
      ref={checkout}
      orderId={orderId}
      onReady={() => checkout.current?.focus()}
    />
  )
}

Use update() only for appearance and locale. Passing those values as props is preferable when they already belong to React state.

Use modals, routes, and server rendering

Render Checkout only while an application-owned modal is open. Closing the modal then unmounts the component, which removes its event subscription and destroys its Checkout instance. Keep scrolling, the close policy, and focus return in the modal component.

The adapter mounts Checkout in an effect, so it does not access the browser during React's server render. In frameworks that distinguish Server and Client Components, render Checkout from a Client Component. For example, add 'use client' to the component that imports @inttegro/react in the Next.js App Router.