Getting Started Guide

@clickaroo/checkout-ui is a comprehensive checkout page component library designed for React applications, providing a complete checkout flow solution. The library includes core features such as customer information collection, delivery address management, payment method selection, and integrates seamlessly with payment systems.

This guide will walk you through different ways to integrate the checkout components into your React application, from the simplest all-in-one solution to fully customized implementations.

Note: If you're new to this library, we recommend starting with the Quick Start which covers installation, basic usage with CheckoutPage, and event callbacks.

ClickarooProvider Configuration

For basic usage of ClickarooProvider, see the Quick Start section.

Advanced Configuration:

You can customize the behavior by passing a config object:

<ClickarooProvider
  config={{
    keyPrefix: 'clro_',
    params: ['token', 'sub4'],
    cookieOptions: {
      expires: 30,
      path: '/',
      sameSite: 'lax',
    },
    debug: false,
    enableSentry: false,
    SentryConfig: Partial<BrowserOptions>
  }}
>
  {/* Your checkout components */}
</ClickarooProvider>

Config Parameters:

Fastest Integration

The simplest way to integrate is using the CheckoutPage component, which includes the complete checkout flow. With this single component, you can quickly integrate a full-featured checkout experience.

👉 See the Use Checkout All in One for detailed instructions and examples.

Payment-Only Integration

If you only need independent payment functionality, you can use the PaymentMethods component or ExpressButtons component separately.

Using PaymentMethods

import { CheckoutProvider, PaymentMethods, ClickarooProvider } from '@clickaroo/checkout-ui';
 
function PaymentOnly() {
  return (
    <ClickarooProvider>
      <CheckoutProvider baseUrl="https://api.clickaroo.io" cart={[...]}>
        <PaymentMethods 
          onPaymentInfoComplete={...}
          options={...}
          styles={...}
        />
      </CheckoutProvider>
    </ClickarooProvider>
  );
}

To complete the full payment flow (including order submission), the code above is not sufficient. You'll need to use the API & hooks provided by the library:

1. Update customer and address information using updateCustomerInfo and updateDeliveryAddress from useCheckoutContext hook
2. Create a custom submit button that calls submitOrder from the useOrderSubmission hook when clicked

Using Express Buttons

import { CheckoutProvider, ExpressButtons, ClickarooProvider } from '@clickaroo/checkout-ui';
 
function PaymentWithExpress() {
  return (
    <ClickarooProvider>
      <CheckoutProvider baseUrl="https://api.clickaroo.io" cart={[...]}>
        <ExpressButtons 
          options={...}
          onClick={...}
          onConfirm={...}
          onOrderSubmit={...}
          onOrderCreated={...}
          onOrderSuccess={...}
          onOrderConfirmed={...}
        />
      </CheckoutProvider>
    </ClickarooProvider>
  );
}

The ExpressButtons component provides parameters to configure payment options and monitor the payment flow.

When users click an express payment button, the corresponding payment form will be automatically generated to collect customer and address information. Therefore, using express payment is very convenient.

Note: Both PaymentMethods and ExpressButtons components must be wrapped in ClickarooProvider and CheckoutProvider when used independently

Custom Checkout Integration

You can build a custom checkout page by mixing and matching the library's built-in components with your own custom components. This gives you full control over the layout, styling, and user experience while leveraging the library's functionality.

You can replace some built-in components with your own custom implementations, but PaymentMethods and ExpressButtons must always be used from the library as they contain critical payment logic that cannot be customized.

import { 
  CheckoutProvider, 
  PaymentMethods,
  ClickarooProvider,
  useCheckoutContext,
  useOrderSubmission
} from '@clickaroo/checkout-ui';
 
function CustomCheckout() {
  const cart = [{ sku: "TEST001", offerPricePoint: "OPP-TEST001" }];
 
  return (
    // All components must be wrapped in ClickarooProvider and CheckoutProvider
    <ClickarooProvider>
      <CheckoutProvider baseUrl="https://api.clickaroo.io" cart={cart}>
        <MyCustomCustomerInfo />
        <MyCustomDeliveryAddress />
        <PaymentMethods /> {/* Required - cannot be customized */}
        <MyCustomSubmitButton />
      </CheckoutProvider>
    </ClickarooProvider>
  );
}
 
// Use hooks to build custom components
function MyCustomCustomerInfo() {
  const { customerInfo, updateCustomerInfo } = useCheckoutContext();
  // use hook to update form data
  updateCustomerInfo({ firstName: 'xxx', lastName: 'xxx', ...})
}
 
function MyCustomDeliveryAddress() {
  const { deliveryAddress, updateDeliveryAddress } = useCheckoutContext();
  // Your custom form implementation
}
 
function MyCustomSubmitButton() {
  const { isFormValid } = useCheckoutContext();
  // use hook to handle order submission
  const { isSubmitting, submitOrder } = useOrderSubmission();
  // Your custom button implementation
}

APIs & Hooks

As mentioned above, the component library provides HTTP APIs and React Hooks for more granular control and advanced use cases.

HTTP APIs

• getPricePointInfo - Get price point information (supports single or multiple price points)
• createOrder - Create an order with the provided order data
• getOrderDetail - Get detailed information about an order by order code

React Hooks

• useCheckoutContext - Access checkout state and update functions (customer info, delivery address, form validation)
• useOrderSubmission - Handle order submission with loading states and error handling
• useOrderDetail - Fetch order details
• useClickarooParams - Access Clickaroo parameters (token, sub4, etc.) managed by ClickarooProvider