cimplify

Checkout Lifecycle

Checkout is a state machine. The SDK manages transitions automatically via processCheckout() or processAndResolve().

State machine
preparing -> processing -> awaiting_authorization -> polling -> finalizing -> success
                                                                              \-> failed

(Recovery path)
recovering -> polling -> finalizing -> success | failed

Status reference

StatusMeaning
preparingValidating cart and payment context
processingSubmitting checkout to payment backend
awaiting_authorizationWaiting for OTP/PIN/3DS/popup authorization
pollingPolling payment status until terminal result
finalizingAssembling order and optional Link enrollment
recoveringResuming interrupted checkout from persisted state
successOrder created with full details
failedTerminal failure with error code

Headless usage

TYPESCRIPT
import { createCimplifyClient, generateIdempotencyKey } from "@cimplify/sdk";

const client = createCimplifyClient();

const result = await client.checkout.processAndResolve({
  cart_id: "cart_123",
  order_type: "delivery",
  customer: { name: "Jane", email: "jane@example.com", phone: "+233501234567" },
  address_info: { address: "123 Main St", city: "Accra" },
  payment_method: "mobile_money",
  idempotency_key: generateIdempotencyKey(),

  on_status_change: (status, context) => {
    console.log(status, context.display_text);
  },
});

if (result.ok && result.value.success) {
  console.log("Order:", result.value.order);
}

Status callback context

TYPESCRIPT
type CheckoutStatusContext = {
  display_text?: string;
  authorization_type?: "otp" | "pin";
  poll_attempt?: number;
  max_poll_attempts?: number;
  order_id?: string;
  order_number?: string;
  provider?: string;
};

Recovery

Element-based flows persist recovery state in localStorage with a 10-minute TTL. If a shopper refreshes during awaiting_authorization, checkout resumes from recovering instead of restarting.

Idempotency

Every processAndResolve() call auto-generates an idempotency key if not provided. Duplicate submissions with the same key are safely rejected by the backend.

TYPESCRIPT
import { generateIdempotencyKey } from "@cimplify/sdk";

const key = generateIdempotencyKey(); // "idem_abc123..."

// Safe to retry with the same key on timeout
const result = await client.checkout.processAndResolve({
  cart_id: "cart_123",
  idempotency_key: key,
  // ...
});

On timeouts or network failures, always poll existing order/payment status before retrying a charge.

Related

Element Events

PostMessage model and React callbacks

Headless Checkout

Full lifecycle implementation guide