Customization

Customize your Web unified checkout

You can customize the Unified Checkout to support your checkout context and brand guidelines by using Layouts and Styling APIs

1. Layouts

Choose a layout that fits well with your UI pattern. There are two types of layout options as listed below. The layout defaults to accordion if not explicitly specified.

1.1 Accordion layout

The accordion layout displays payment methods vertically using an accordion. To use this layout, set the value for layout to accordion. You also have the option to specify other properties, such as those shown in the following example.

var paymentElementOptions = {
 layout: {
   type: 'accordion',
   defaultCollapsed: false,
   radios: true,
   spacedAccordionItems: false
 },
}

—------or—---------


var paymentElementOptions = {
 layout: 'accordion'
}

<PaymentElement id="payment-element" options={paymentElementOptions} />

1.2 Tabs layout

The tabs layout displays payment methods horizontally using tabs. To use this layout, set the value for layout to tabs. You also have the option to specify other properties, such as tabs or collapsed.

var paymentElementOptions = {
 layout: 'tabs'
}

<PaymentElement id="payment-element" options={paymentElementOptions} />

2. Wallets

The wallet customization feature lets users configure payment options like Apple Pay, Google Pay, PayPal, and Klarna. It includes a walletReturnUrl for post-payment redirects and a style property to customize the wallet's appearance, offering flexibility for seamless integration.

var paymentElementOptions = {
    wallets: {
      walletReturnUrl: `${window.location.origin}`,
      applePay: "auto",
      googlePay: "auto",
      payPal: "auto",
      klarna: "never",
      style: {
        theme: "dark",
        type: "default",
        height: 55,
        buttonRadius: 4,
      },
    },
  }
  
<PaymentElement id="payment-element" options={paymentElementOptions} />

3. Styling variables

The Styling APIs could be used to blend the Unified Checkout with the rest of your app or website.

4. Rules

The rules option is a map of CSS-like selectors to CSS properties, allowing granular customization of individual components. After defining your theme and variables, use rules to seamlessly integrate Elements to match the design of your site. The selector for a rule can target any of the public class names in the Element, as well as the supported states, pseudo-classes, and pseudo-elements for each class. For example, the following are valid selectors:

.Tab, .Label, .Input
.Tab:focus
.Input--invalid, .Label--invalid
.Input::placeholder
.billing-section, .billing-details-text

Each class name used in a selector supports an allowlist of CSS properties that you specify using camel case (for example, boxShadow for the box-shadow property). The following is the complete list of supported class names and corresponding states, pseudo-classes, and pseudo-elements.

Tabs

.Tab, .Label, .Input
.Tab:focus
.Input--invalid, .Label--invalid
.Input::placeholder

Tabs

const appearance = {
  variables: {
    buttonBackgroundColor: "#FFFFFF",
    buttonTextColor: "#000000",
    // ... along with other variables
  },
  rules: {
    ".TabLabel": {
      overflowWrap: "break-word",
    },
    ".Tab--selected": {
      display: "flex",
      gap: "8px",
      flexDirection: "row",
      justifyContent: "center",
      alignItems: "center",
      padding: "15px 32px",
      background: "linear-gradient(109deg,#f48836,#f4364c)",
      color: "#ffffff",
      fontWeight: "700",
      borderRadius: "25px",
    },
    ".Tab--selected:hover": {
      display: "flex",
      gap: "8px",
      flexDirection: "row",
      justifyContent: "center",
      alignItems: "center",
      padding: "15px 32px",
      background: "linear-gradient(109deg,#f48836,#f4364c)",
      borderRadius: "25px",
      color: "#ffffff !important",
      fontWeight: "700",
    },
  },
};

const elements = hyper.elements({ clientSecret, appearance });

Form Inputs

Checkbox

5. Languages

Hyperswitch Unified Checkout supports localization in 6 languages. By default, the Unified Checkout SDK will detect the locale of the customer’s browser and display the localized version of the payment sheet if that locale is supported. In case it is not supported, we default to English. To override, you can send locale in hyper.elements (options)

We support the following locales -

Arabic (ar)
Catalan (ca)
Chinese (zh)
Deutsch (de)
Dutch (nl)
English (en)
EnglishGB (en-GB)
FrenchBelgium (fr-BE)
French (fr)
Hebrew (he)
Italian (it)
Japanese (ja)
Polish (pl)
Portuguese (pt)
Russian (ru)
Spanish (es)
Swedish (sv)

If you need support for locales other than the ones mentioned above, please contact the Hyperswitch team. Now you can test the payments on your app and go-live!

6. Confirm Button

The Styling APIs could be used to blend the Confirm Payment Button (handled by SDK) with your app.

7. More Configurations

Branding

You can decide whether to display the Hyperswitch branding using the branding prop

var paymentElementOptions = {
 ...,
 branding: "never", // choose between "never" and "always"
}

<PaymentElement id="payment-element" options={paymentElementOptions} />

Payment Methods Header Text

Customize the header text for the section displaying available payment methods.

var paymentElementOptions = {
 ...,
 paymentMethodsHeaderText: "Select Payment Method",
}

<PaymentElement id="payment-element" options={paymentElementOptions} />

Saved Payment Methods Header Text

Customize the header text for the section displaying saved payment methods.

var paymentElementOptions = {
 ...,
 savedPaymentMethodsHeaderText: "Saved Payment Methods",
}

<PaymentElement id="payment-element" options={paymentElementOptions} />

Custom Message for Card Terms

We provide a default message for card terms i.e.

`By providing your card information, you allow ${company_name} to charge your card for future payments in accordance with their terms.`

If you would like to customize this message, you can do so by using the customMessageForCardTerms property in the paymentElementOptions object.

var paymentElementOptions = {
 ...,
 customMessageForCardTerms: "Custom message for Card terms",
}

<PaymentElement id="payment-element" options={paymentElementOptions} />

Hide Card Nickname Field

The hideCardNicknameField property allows you to hide the card nickname field when saving a card.

var paymentElementOptions = {
  ...,
  hideCardNicknameField: true,  // default - false
};

<PaymentElement id="payment-element" options={paymentElementOptions} />;

Hide Expired Saved Payment Methods

The hideExpiredPaymentMethods property allows you to control whether expired saved payment methods are hidden or not.

var paymentElementOptions = {
  ...,
  hideExpiredPaymentMethods: false, // default - false
};

<PaymentElement id="payment-element" options={paymentElementOptions} />;

Show Card Form by Default

The showCardFormByDefault property determines whether the card form is displayed by default or not.

var paymentElementOptions = {
  ...,
  showCardFormByDefault: true,
};

<PaymentElement id="payment-element" options={paymentElementOptions} />;

Terms

The terms property allows you to configure the display of terms for various payment methods.

var paymentElementOptions = {
  ...,
  terms: {
    auBecsDebit: "always",
    bancontact: "auto",
    card: "never",
    ideal: "auto",
    sepaDebit: "always",
    sofort: "never",
    usBankAccount: "auto",
  },
};

<PaymentElement id="payment-element" options={paymentElementOptions} />;

Display Saved Payment Methods

The displaySavedPaymentMethods property determines whether saved payment methods are displayed.

var paymentElementOptions = {
  ...,
  displaySavedPaymentMethods: false,
};

<PaymentElement id="payment-element" options={paymentElementOptions} />;

Display Saved Payment Methods Checkbox

The displaySavedPaymentMethodsCheckbox property determines whether the "Save payment methods" checkbox is displayed.

var paymentElementOptions = {
  ...,
  displaySavedPaymentMethodsCheckbox: false, 
};

<PaymentElement id="payment-element" options={paymentElementOptions} />;

Payment Method Order

The paymentMethodOrder property allows you to specify the order in which payment methods are displayed.

var paymentElementOptions = {
  ...,
  paymentMethodOrder: ["card", "ideal", "sepaDebit", "sofort"],
};

<PaymentElement id="payment-element" options={paymentElementOptions} />;

Business

The business property allows you to specify a business name to be attached to the terms. By default merchant name will be taken as business name.

var paymentElementOptions = {
  ...,
  business: {
    name: "Example Business",
  },
};

<PaymentElement id="payment-element" options={paymentElementOptions} />;

Read Only

The readOnly property puts the SDK into read-only mode, disabling all interactions.

var paymentElementOptions = {
  ...,
  readOnly: true,
};

<PaymentElement id="payment-element" options={paymentElementOptions} />;

Next step:

Last updated 15 days ago