Element Events

Elements communicate via postMessage between your page and link.cimplify.io iframes. The React SDK wraps these into typed callback props.

React SDK callbacks

// Unified checkout element (recommended)
<CimplifyCheckout
  onStatusChange={(status, context) => console.log(status, context.display_text)}
  onComplete={(result) => console.log(result.order?.id)}
  onError={(error) => console.error(error.code, error.message)}
/>

// Standalone auth element
<AuthElement
  onReady={() => console.log("auth ready")}
  onAuthenticated={(data) => console.log(data.token)}
  onRequiresOtp={(data) => console.log(data.contactMasked)}
  onError={(error) => console.error(error.code, error.message)}
/>

Core element events

Event	Elements	Payload
`ready`	checkout, auth, address, payment	`{ height }`
`authenticated`	checkout, auth	`{ accountId, customerId, token, customer }`
`requires_otp`	checkout, auth	`{ contactMasked }`
`order_type_changed`	checkout	`{ orderType }`
`contact_provided`	checkout	`{ contact, contactType }`
`address_selected`	checkout	`{ address }`
`change`	address, payment	`{ address, saveToLink }` or `{ paymentMethod, saveToLink }`
`checkout_status`	checkout	`{ status, context }`
`checkout_complete`	checkout	`{ success, order?, error?, enrolled_in_link? }`
`request_submit`	checkout	`{}`
`error`	all	`{ code, message }`

Checkout status values

The checkout_status event fires at each state transition. See Checkout Lifecycle for the full state machine.

// Status values:
// "preparing" | "recovering" | "processing" | "awaiting_authorization"
// | "polling" | "finalizing" | "success" | "failed"

PostMessage protocol

Parent to iframe

Message	Purpose
`INIT`	Initialize element with config
`SET_TOKEN`	Pass access token to iframe (skipped for unified checkout)
`SET_CART`	Send cart data (line items, totals, tax) for inline order summary
`GET_DATA`	Request current element data
`PROCESS_CHECKOUT`	Trigger checkout from checkout/payment element
`ABORT_CHECKOUT`	Cancel in-progress checkout
`REFRESH_TOKEN`	Request token refresh from element
`LOGOUT`	Log out user from element

Iframe to parent

Message	Purpose
`READY`	Element loaded and ready
`HEIGHT_CHANGE`	Auto-resize iframe height
`AUTHENTICATED`	Auth completed with token (from checkout or auth element)
`TOKEN_REFRESHED`	Access token was refreshed
`REQUIRES_OTP`	OTP/PIN entry needed (from checkout or auth element)
`ORDER_TYPE_CHANGED`	User changed order type in checkout element
`CONTACT_PROVIDED`	User provided email or phone in checkout element
`ADDRESS_CHANGED`	Address input updated
`ADDRESS_SELECTED`	Saved address selected
`PAYMENT_METHOD_SELECTED`	Payment method chosen
`CHECKOUT_STATUS`	Checkout state machine transition
`CHECKOUT_COMPLETE`	Checkout reached terminal state
`REQUEST_SUBMIT`	Checkout element's built-in submit button was pressed
`ERROR`	Error occurred in element
`LOGOUT_COMPLETE`	User logged out from element

React callback mapping

PostMessage	React Prop	Components
`READY`	`onReady`	AuthElement
`AUTHENTICATED`	`onAuthenticated`	AuthElement
`REQUIRES_OTP`	`onRequiresOtp`	AuthElement
`ERROR`	`onError`	AuthElement, CimplifyCheckout
`ADDRESS_CHANGED` / `PAYMENT_METHOD_SELECTED`	`onChange`	AddressElement, PaymentElement
`CHECKOUT_STATUS`	`onStatusChange`	CimplifyCheckout
`CHECKOUT_COMPLETE`	`onComplete`	CimplifyCheckout
`REQUEST_SUBMIT`	(handled internally)	CimplifyCheckout triggers `processCheckout()` automatically

Checkout lifecycle events

TYPESCRIPT

const result = await elements.processCheckout({
  cart_id: "cart_123",
  order_type: "delivery",
  on_status_change: (status, context) => {
    // status: "preparing" | "recovering" | "processing"
    //       | "awaiting_authorization" | "polling" | "finalizing"
    //       | "success" | "failed"
    console.log(status, context);
  },
});

// result: { success, order?, error?, enrolled_in_link? }

Security

The SDK validates message origins and only accepts events from *.cimplify.io and localhost (in dev). This isolates sensitive auth/payment UI from merchant-page scripts.

Use SDK callbacks instead of raw postMessage listeners. The SDK handles origin validation and type safety automatically.

Checkout Lifecycle

State machine and recovery model

Elements Checkout Guide

Step-by-step element integration