Checkout analytics

onInstrument gives your application a feed of checkout funnel and failure signals that you can forward to your own analytics destination. It answers the question backend outcomes cannot: not "how many payments succeeded", but "where did the buyers who never paid drop out".

Upgrade @flopay/react and @flopay/shared to FloPay SDK 1.7.0 or later before wiring it up.

What the feed is

The SDK maintains a large internal checkout taxonomy for its own diagnostics. onInstrument is not that taxonomy. It is a small, allowlisted projection of it onto a stable public contract — seven lifecycle names and one error name with four phases, and nothing else.

That distinction is the point of the feature. The internal taxonomy carries no compatibility guarantee and changes freely; the projection is versioned and will not change shape under you. Build your funnel on the projection.

Wiring it up

Pass onInstrument to FloPayCheckout. This is the typical integration — the component owns its own provider, so one callback covers the whole checkout.

import { FloPayCheckout } from '@flopay/react';
import type { FloInstrumentEvent } from '@flopay/react';

function forwardCheckoutInstrument(event: FloInstrumentEvent) {
  window.analytics?.track(event.name, {
    schemaVersion: event.schemaVersion,
    gateway: event.gateway,
    phase: event.name === 'checkout_error' ? event.phase : undefined,
  });
}

export function CheckoutPage({ sessionId }: { sessionId: string }) {
  return (
    <FloPayCheckout
      sessionId={sessionId}
      onInstrument={forwardCheckoutInstrument}
      onComplete={() => router.push('/success')}
    />
  );
}

If you compose the payment surfaces yourself rather than using FloPayCheckout, pass the same callback to FloPayProvider instead:

<FloPayProvider flopay={flopayPromise} onInstrument={forwardCheckoutInstrument}>
  <YourOwnCheckoutSurface />
</FloPayProvider>

Use one or the other, not both for the same checkout. FloPayCheckout already forwards the instruments raised by the provider it owns.

The event shape

Every event is a FloInstrumentEvent — a discriminated union on name:

type FloInstrumentEvent =
  | { schemaVersion: 1; gateway?: 'stripe' | 'paypal'; name: FloInstrumentLifecycleName }
  | {
      schemaVersion: 1;
      gateway?: 'stripe' | 'paypal';
      name: 'checkout_error';
      phase: FloInstrumentErrorPhase;
    };

Because the union is discriminated, narrow on name before reading phase:

function describe(event: FloInstrumentEvent): string {
  if (event.name === 'checkout_error') {
    return `failed at ${event.phase}`; // `phase` only narrows here
  }
  return event.name;
}

The catalog

Seven lifecycle names describe progress through the checkout:

checkout_error carries a phase naming the stage that failed:

Asserting catalog parity in a test

@flopay/shared exports the whole catalog as FLO_INSTRUMENT_CATALOG specifically so you can pin your funnel to it. Assert that every catalog entry has a home in your analytics, and a future SDK release that adds a signal fails your test rather than silently dropping out of your dashboard:

import { FLO_INSTRUMENT_CATALOG } from '@flopay/shared';
import { FUNNEL_STEPS } from './funnel';

it('handles every instrument the SDK can emit', () => {
  const catalogKeys = FLO_INSTRUMENT_CATALOG.map((entry) =>
    'phase' in entry ? `${entry.name}:${entry.phase}` : entry.name,
  );

  expect(Object.keys(FUNNEL_STEPS).sort()).toEqual(catalogKeys.sort());
});

Error phases are separate catalog entries rather than a nested list, so this parity check covers each arm of your failure attribution independently.

Building a funnel

The catalog is ordered, but the events are not a strict sequence — a checkout can end at any step, and some steps repeat.

A "logical checkout" is one mounted checkout running one session: the SDK keys deduplication on the sessionId (or on the inline createSession draft) currently in play. Swapping in a different session resets the once-only set, so the buyer's second session reports its own checkout_mount. Unmounting and remounting the component starts over too — if your page can do that, deduplicate on your own session identifier as well.

So aggregate per session, reducing the repeatable names to a boolean reached-or-not, and keep the attempt count as its own metric:

import type { FloInstrumentEvent } from '@flopay/react';

type FunnelRow = {
  reached: Set<FloInstrumentEvent['name']>;
  attempts: number;
  challenges: number;
  failedAt?: string;
};

function record(row: FunnelRow, event: FloInstrumentEvent): FunnelRow {
  row.reached.add(event.name);

  if (event.name === 'process_attempt') row.attempts += 1;
  if (event.name === '3ds_challenge') row.challenges += 1;
  if (event.name === 'checkout_error') row.failedAt = event.phase;

  return row;
}

Then read the funnel off reached, which is idempotent regardless of how many attempts the buyer made:

attempts > 1 is a retry signal: those buyers were declined at least once and tried again. Segmenting your completion rate by attempts separates "declined and gave up" from "declined and recovered", which are very different problems. Likewise challenges > 0 isolates the buyers who had to leave for a bank authentication step, historically the largest single source of late-funnel abandonment.

For layout="buttons", card_expanded splits the funnel by method: buyers with card_expanded chose the card path, and those without it went to a wallet or PayPal. Combine it with gateway to attribute the outcome.

The feed deliberately does not include a success event — onInstrument covers the path to payment, and the payment outcome itself is already yours through onComplete and your backend records. Join them on your own session or order identifier.

Independence from telemetry

If you want no merchant analytics, omit onInstrument. Nothing is emitted when there is no callback to receive it.

Privacy guarantees

The feed is an allowlist, not a redaction pass. An event can only ever be assembled from the fields documented above, so it structurally cannot carry anything else. It never contains:

• Card numbers, expiry dates, CVCs, or any other card detail
• Payment tokens, nonces, client secrets, or publishable keys
• Provider object identifiers — no Stripe payment intent, customer, or payment method ids, no PayPal order ids
• Buyer identity — no email, name, address, user id, or IP
• Amounts, currencies, product codes, or cart contents
• Free-text error messages from any provider

That is why checkout_error reports a coarse phase rather than a message or a provider error code: a phase cannot leak. It also means the feed is safe to forward directly to a third-party analytics destination without a scrubbing step in between.

If you need the detail the feed withholds — decline codes, amounts, the buyer — take it from onDecline, onError, or your own backend records, where you control the destination.

Reference

• FloPayCheckout props
• FloPayProvider props
• FloInstrumentEvent
• FLO_INSTRUMENT_CATALOG