CimplifyCheckout (React)

<CimplifyCheckout> gives the merchant a complete checkout on their own page: contact capture, Cimplify Link verification, saved details, address, payment, provider authorization, submit, recovery, and status updates. The SDK creates the checkout iframe and handles the message bridge, OAuth hand-off, checkout processing, aborts, and completion events.

Under the iframe, checkout mints a durable purchase intent, renders one immutable terms revision, and confirms that exact revision. A material or money change emits reviewing_terms; ctx.replacement_terms and ctx.terms_deltas let the host mirror the review state without guessing from cart totals.

For most storefronts, this is the embedded checkout integration to use.

Required Auth Setup

Checkout uses the storefront's OAuth client when a shopper chooses to use Cimplify saved details. Add the route handlers from Sign in with Cimplify, then expose these browser env vars:

NEXT_PUBLIC_CIMPLIFY_CLIENT_ID=cim_client_…
NEXT_PUBLIC_CIMPLIFY_REDIRECT_URI=https://your-store.com/auth/callback

These values let checkout verify the shopper through auth.cimplify.io and return to the merchant page.

Example

import { CimplifyClient } from "@cimplify/sdk";
import { CimplifyCheckout } from "@cimplify/sdk/react";

const client = new CimplifyClient({
  publicKey: process.env.NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY!,
  credentials: "include",
});

export function CheckoutScreen({ cartId }: { cartId: string }) {
  return (
    <CimplifyCheckout
      client={client}
      cartId={cartId}
      orderTypes={["delivery", "pickup"]}
      defaultOrderType="delivery"
      submitLabel="Pay now"
      appearance={{
        theme: "light",
        variables: { primaryColor: "#059669", borderRadius: "0.85rem" },
      }}
      onStatusChange={(status, ctx) => {
        console.log(status, ctx.display_text);
      }}
      onComplete={(result) => {
        if (result.success) {
          window.location.assign(`/orders/${result.order!.id}`);
        }
      }}
      onError={(err) => console.error(err.code, err.message)}
    />
  );
}

Props

For a hosted session or paylink, bind the element to the authority the server already minted. Do not pass the shopper's current cart as a substitute:

<CimplifyCheckout
  client={client}
  intentId={session.intent_id}
  initialTerms={session.terms}
  onComplete={handleComplete}
/>

initialTerms is sent in the initial iframe handshake so the screen can render before Pay is clicked. The iframe still fetches the intent again and confirms the current server-issued terms; the hint is never payment authority.

Checkout Sign-In UX

Checkout collects email or phone inline. Once the contact is valid, the SDK starts Cimplify OAuth with that contact as login_hint and checkout-oriented copy.

If the shopper already has a matching Cimplify session, checkout loads saved details without showing verification UI. If the shopper needs to verify, hosted auth opens directly to OTP/passkey for that contact. The checkout iframe only receives the access token after verification succeeds.

The UI does not reveal account existence before verification. It can show a generic "Use saved details with Cimplify" action after a valid contact, then Cimplify decides whether silent sign-in, OTP, passkey, consent, or account switching is needed.

Account Switching

When the shopper is signed in during checkout, checkout shows the verified contact and a Change action. Choosing Change starts Cimplify OAuth with an account-switch prompt so the shopper can use a different Cimplify account before selecting saved details or entering new payment information.

Agent Checklist

1. Use <CimplifyCheckout> for embedded checkout.
2. Set NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY, NEXT_PUBLIC_CIMPLIFY_CLIENT_ID, and NEXT_PUBLIC_CIMPLIFY_REDIRECT_URI.
3. Add /auth/callback with both GET and POST handlers.
4. Use cpk_test_ / cpk_live_ for Cimplify public keys.
5. Leave shopper verification to auth.cimplify.io.
6. Load saved Link details only after verification completes.

Next

• Appearance API: Theme checkout
• Vanilla checkout: Same checkout controller without React
• Raw checkout iframe: Manual postMessage integration