ExpressButtons

A component that displays express payment buttons (Apple Pay, Google Pay, PayPal, etc.). This component handles the complete express checkout flow including order submission, payment confirmation, and address updates.

  • Must be used inside CheckoutProvider.
  • Handles express payment flow from click to confirmation.
  • Automatically handles user and address information from express payment buttons, no manual collection required.

Express Buttons

Props

styles

Custom CSS styles for the component container.

styles?: React.CSSProperties

options

Express checkout element configuration options.

options?: StripeExpressCheckoutElementOptions
Property Type Description
allowedShippingCountries string[] An array of two-letter ISO country codes representing which countries are eligible shipping locations
applePay ApplePayOption Apple Pay specific configuration options
billingAddressRequired boolean Whether the billing address should be collected in the payment interface
business {name: string} Provide information about your business that will be displayed in the payment interface. This information will be retrieved from your account if not provided
buttonHeight number Manually sets the height of the buttons shown
buttonTheme ButtonThemeOption Controls the color of each button
buttonType ButtonTypeOption Specifies the type of each button
emailRequired boolean Whether the email address should be collected in the payment interface
layout LayoutOption Specifies how buttons should be laid out in relation to each other
lineItems LineItem[] Array of line items to display in the payment interface
paymentMethodOrder string[] Override the order in which payment methods are displayed. By default, uses a dynamic ordering that optimizes payment method display for each user
paymentMethods ExpressCheckoutPaymentMethodsOption Control payment method display in the Express Checkout Element
phoneNumberRequired boolean Whether the phone number should be collected in the payment interface
shippingAddressRequired boolean Whether the shipping address should be collected in the payment interface
shippingRates ShippingRate[] Array of shipping rates to display in the payment interface

Default options:

{
  emailRequired: true,
  phoneNumberRequired: true,
  shippingAddressRequired: true,
  paymentMethods: {
    applePay: 'always',
    googlePay: 'always',
    paypal: 'auto',
    link: 'auto',
    amazonPay: 'auto',
    klarna: 'auto',
  }
}

onClick

Callback function triggered when an express payment button is clicked.

onClick?: (event: StripeExpressCheckoutElementClickEvent) => void

Parameter Description:

Parameter Type Description
event StripeExpressCheckoutElementClickEvent Express checkout element click event

onConfirm

Callback function triggered when express payment is confirmed by the user, before order submission.

onConfirm?: (event: StripeExpressCheckoutElementConfirmEvent) => void

Parameter Description:

Parameter Type Description
event StripeExpressCheckoutElementConfirmEvent Express checkout element confirm event

onOrderSubmit

Callback function triggered before order API call, allowing you to set metadata dynamically.

onOrderSubmit?: OnOrderSubmitCallback

Parameter Description:

Parameter Type Description
products CheckoutCartItem[] Cart items array at submission time
totalAmount number Total amount at submission time in cents (e.g., 9999 represents $99.99)
setMetadata (metadata: Record<string, string>) => void Function to dynamically set metadata for the order.
• Merges with metadata passed via CheckoutProvider metadata prop
• Can be retrieved through orderDetail

onOrderCreated

Callback function triggered after the order is successfully created.

onOrderCreated?: OnOrderCreatedCallback

Parameter Description:

Parameter Type Description
result CreateOrderResponse Order creation result containing orderCode, tradeCode, clientSecret, etc.

onOrderSuccess

Callback function triggered after the payment is successfully processed.

onOrderSuccess?: OnOrderSuccessCallback

Parameter Description:

Parameter Type Description
orderCode string Order code
tradeCode string Trade code (optional)

onOrderConfirmed

Same as onOrderSuccess, triggered after the payment is successfully processed.

onOrderConfirmed?: OnOrderConfirmedCallback

Parameter Description:

Parameter Type Description
orderCode string Order code
tradeCode string Trade code (optional)

Usage Examples

import { ExpressButtons, CheckoutProvider, ClickarooProvider } from '@clickaroo/checkout-ui';
 
function CustomCheckout() {
  const cart = [
    {
      sku: "TEST001",
      offerPricePoint: "OPP-TEST001",
    }
  ];
 
  return (
    <ClickarooProvider>
      <CheckoutProvider
        baseUrl="https://api.clickaroo.io"
        cart={cart}
      >
        <ExpressButtons
          options={{
            layout: {
              maxColumns: 1,
              overflow: "never"
            },
          }}
          onClick={(event) => {
            console.log('Express button clicked', event.expressPaymentType);
            event.resolve?.();
          }}
          onConfirm={(event) => {
            console.log('Express payment confirmed', event);
          }}
        />
      </CheckoutProvider>
    </ClickarooProvider>
  );
}

Features

Automatic Information Collection

When a user completes express checkout, the component automatically extracts and updates:

  • Customer Information: Email, phone, first name, last name (from shipping address name)
  • Delivery Address: Full address details from the express payment buttons

Payment Flow

  1. User clicks express payment button → onClick callback
  2. User confirms payment → onConfirm callback
  3. Order is submitted → onOrderSubmit callback
  4. Order is created → onOrderCreated callback
  5. Payment is confirmed → onOrderSuccess / onOrderConfirmed callbacks

Key Types

ApplePayOption

Apple Pay specific configuration options:

export type ApplePayOption = {
  recurringPaymentRequest: {
    /**
    * The description of the payment that the customer will see in their Apple Pay wallet.
    */
    paymentDescription: string;
 
    /**
    * The URL to manage items related to the recurring payment on your website.
    */
    managementURL: string;
    regularBilling: ApplePayRegularBilling;
    trialBilling?: ApplePayRegularBilling;
 
    /**
    * The billing agreement label that is displayed to the customer in the Apple Pay payment interface.
    */
    billingAgreement?: string;
  };
  deferredPaymentRequest?: null;
  automaticReloadPaymentRequest?: null;
}
Field Type Description
recurringPaymentRequest object Configuration for recurring payment requests
recurringPaymentRequest.paymentDescription string The description of the payment that the customer will see in their Apple Pay wallet
recurringPaymentRequest.managementURL string The URL to manage items related to the recurring payment on your website
recurringPaymentRequest.regularBilling ApplePayRegularBilling Regular billing configuration
recurringPaymentRequest.trialBilling ApplePayRegularBilling Trial billing configuration (optional)
recurringPaymentRequest.billingAgreement string The billing agreement label that is displayed to the customer in the Apple Pay payment interface (optional)
deferredPaymentRequest null Deferred payment request (optional)
automaticReloadPaymentRequest null Automatic reload payment request (optional)

ButtonThemeOption

Controls the color of each button:

export type ButtonThemeOption = {
  applePay?: 'black' | 'white' | 'white-outline';
  googlePay?: 'black' | 'white';
  paypal?: 'gold' | 'blue' | 'silver' | 'white' | 'black';
};
Field Type Description
applePay 'black' | 'white' | 'white-outline' Apple Pay button color
googlePay 'black' | 'white' Google Pay button color
paypal 'gold' | 'blue' | 'silver' | 'white' | 'black' PayPal button color

ButtonTypeOption

Specifies the type of each button:

export type ButtonTypeOption = {
  applePay?: 'add-money' | 'book' | 'buy' | 'check-out' | 'contribute' | 'donate' | 'order' | 'plain' | 'reload' | 'rent' | 'subscribe' | 'support' | 'tip' | 'top-up';
  googlePay?: 'book' | 'buy' | 'checkout' | 'donate' | 'order' | 'pay' | 'plain' | 'subscribe';
  paypal?: 'paypal' | 'buynow' | 'checkout' | 'pay';
};
Field Type Description
applePay 'add-money' | 'book' | 'buy' | 'check-out' | 'contribute' | 'donate' | 'order' | 'plain' | 'reload' | 'rent' | 'subscribe' | 'support' | 'tip' | 'top-up' Apple Pay button type
googlePay 'book' | 'buy' | 'checkout' | 'donate' | 'order' | 'pay' | 'plain' | 'subscribe' Google Pay button type
paypal 'paypal' | 'buynow' | 'checkout' | 'pay' PayPal button type

LayoutOption

Specifies how buttons should be laid out in relation to each other:

export type LayoutOption = {
  maxColumns?: number;
  maxRows?: number;
  overflow?: 'auto' | 'never';
};
Field Type Description
maxColumns number Maximum number of columns for button layout
maxRows number Maximum number of rows for button layout
overflow 'auto' | 'never' How to handle overflow when buttons exceed maxColumns/maxRows

LineItem

Line item to display in the payment interface:

export type LineItem = {
  name: string;
  amount: number;
  quantity?: number;
  image?: string;
};
Field Type Description
name string Product name
amount number Amount in cents (e.g., 9999 represents $99.99)
quantity number Quantity (optional)
image string Product image URL (optional)

ShippingRate

Shipping rate to display in the payment interface:

export type ShippingRate = {
  id: string;
  amount: number;
  displayName: string;
};
Field Type Description
id string Unique identifier for the shipping rate
amount number Shipping cost in cents (e.g., 999 represents $9.99)
displayName string Display name for the shipping rate

ExpressCheckoutPaymentMethodsOption

Control payment method display in the Express Checkout Element:

export type ExpressCheckoutPaymentMethodsOption = {
  applePay?: 'always' | 'auto' | 'never';
  googlePay?: 'always' | 'auto' | 'never';
  paypal?: 'always' | 'auto' | 'never';
  link?: 'always' | 'auto' | 'never';
  amazonPay?: 'always' | 'auto' | 'never';
  klarna?: 'always' | 'auto' | 'never';
};
Field Type Description
applePay 'always' | 'auto' | 'never' Display Apple Pay: 'always' shows always, 'auto' shows when available, 'never' hides
googlePay 'always' | 'auto' | 'never' Display Google Pay: 'always' shows always, 'auto' shows when available, 'never' hides
paypal 'always' | 'auto' | 'never' Display PayPal: 'always' shows always, 'auto' shows when available, 'never' hides
link 'always' | 'auto' | 'never' Display Link: 'always' shows always, 'auto' shows when available, 'never' hides
amazonPay 'always' | 'auto' | 'never' Display Amazon Pay: 'always' shows always, 'auto' shows when available, 'never' hides
klarna 'always' | 'auto' | 'never' Display Klarna: 'always' shows always, 'auto' shows when available, 'never' hides