LogoLogo
Explore with DeepWikiJoin Slack CommunityContact Us
  • About Hyperswitch
    • Introduction
    • Payments Suite
    • Payments Modules
      • Cost Observability
      • Revenue Recovery
      • Vault
        • Server to Server Vault tokenization
        • Vault SDK Integration
      • Intelligent Routing
      • Reconciliation
        • Getting Started with Recon
      • Alternate Payment Method Widgets
        • Hyperwidget Integration Guide
    • Roadmap - Q2 2025
      • Previous Roadmap - Q1 2025
      • Previous Roadmap - Q4 2024
      • Previous Roadmap - Q3 2024
      • Previous Roadmap - Q2 2024
      • Previous roadmap - Q1 2024
      • Previous roadmap - Q4 2023
  • Use-Cases
    • For SaaS Businesses
    • For B2B SaaS Businesses
    • For E-Commerce Businesses
    • For Marketplace/Platforms
  • Explore Hyperswitch
    • Payment Orchestration
      • Accept Payments
        • Connectors
          • Activate Connector on Hyperswitch
          • Try a Payment
          • Available Connectors
            • ACI
            • Adyen
            • Airwallex
            • Authorizedotnet
            • Bambora
            • Bank of America
            • Billwerk
            • Bluesnap
            • Braintree
            • Checkout
            • Coinbase
            • Cybersource
              • Apple Pay
              • Google Pay
            • dLocal
            • Fiserv
            • GlobalPayments
            • GoCardless
            • Klarna
            • Mollie
            • MultiSafepay
            • Nuvei
            • OpenNode
            • Paypal
            • PayU
            • Prophetpay
            • Rapyd
            • Shift4
            • Stripe
            • TrustPay
            • Volt
            • Worldline
            • Worldpay
            • Zen
            • Netcetera
              • Authenticating Payments via Netcetera Through HyperSwitch SDK
        • Setup Payment Methods
          • Cards
          • Wallets
            • Apple Pay
              • Web Domain
              • iOS Application
            • Google Pay
            • PayPal
          • Pay Later
          • Banks
            • Bank Debits
            • Bank Redirects
            • Bank Transfers
            • Open Banking
          • Crypto
          • Test Credentials
        • Payment Links
          • Configurations
          • Create Payment Links
          • Secure Payment Links
          • Setup Custom Domain
        • Save a Payment Method
        • Manual Capture
        • Incremental Authorization
        • Tokenization & Card Vault
          • Network Tokenisation
        • Supported Payment Workflows
        • Co-badged Cards
        • Webhooks
      • Process Payouts
        • Getting Started with Payouts
        • Using Saved Payment Methods
        • Smart Router for Payouts
        • Smart Retries in Payout
        • Payout Links
      • Smart Routing
        • Rule Based Routing
        • Volume Based Routing
        • Default Fallback Routing
      • Smart Retries
        • 3DS Step-up Retries
      • 3DS / Strong Customer Authentication
        • Setting up 3DS Decision Manager
        • Native 3DS Authentication
        • External Authentication for 3DS
      • Fraud & Risk Management
        • Activating FRM in Hyperswitch
        • Fraud Blocklist
      • Subscriptions
        • PG Agnostic Card Forwarding
        • Zero Amount Authorization
      • Split Payments
        • Stripe Split Payments
        • Adyen Split Payments
        • Xendit Split Payments
    • Checkout Experience
      • Customizable and Native Integrations
        • Web
          • Node And React
          • Customization
          • Error Codes
          • Node and HTML
          • Vanilla JS and REST API Integration
        • Android
          • Kotlin with Node Backend
          • Customization
          • Features
        • iOS
          • Swift with Node Backend
          • Customization
          • Features
        • React Native
          • React Native with Node Backend
          • Card Widget
          • Customization
        • Flutter
          • Flutter with Node Backend
          • Customization
        • Headless SDK
        • Server Setup
      • Click To Pay
        • Visa Click to Pay: V1 to V2 Migration
      • Payment Methods Management
    • Payment Operations
      • Managing Accounts and Profiles
        • ⚙️Control Centre Account setup
        • Hyperswitch Account Structure
      • Manage Your Team
      • Analytics & operations
        • Exporting payments data
      • Disputes / Chargebacks
      • Surcharge
        • Surcharge Setup guide
      • Multi-Tenancy
      • Data migration
        • Import data to Hyperswitch
        • Export data from Hyperswitch
    • Security and Compliance
      • PCI Compliance
      • Data Security
      • GDPR compliance
      • Identity and Access Management
    • E-commerce Platform Plugins by Hyperswitch
      • 🔌WooCommerce Plugin
        • Setup
        • Roadmap
        • Compatibility
        • FAQs
      • Saleor App
        • Setup
      • Automatic Tax calculation for Express Checkout wallets
  • Hyperswitch open source
    • Overview
      • Run Hyperswitch Locally Using Docker
        • Run Additional Services
      • Development Environment Setup
        • Backend
          • Configure and Run the Application
          • Try out APIs
        • SDK (Frontend)
        • Control Center
    • Deploy on AWS
      • Deploy on AWS using CloudFormation
      • Component-wise Deployment
        • Deploy app server
        • Deploy Control Center
        • Deploy web client
          • Production ready deployment
          • Integrate web client on your web app
          • Playground deployment for prototyping (optional)
        • Deploy Card Vault
          • Production ready deployment on AWS
          • Cloud setup guide
    • Deploy on Kubernetes
      • Deploy on GCP Using Helm Charts
      • Deploy on Azure Using Helm Charts
    • Exploration Guide
    • Account setup
      • Using Hyperswitch Control Center
      • Test a payment
      • Using postman
    • Troubleshooting
  • Testing Payments
  • Check list for Production
    • Going live
      • For SaaS Setup
      • For On-Prem Setup
        • Monitoring
        • PCI compliance
          • Get started
          • Completing the SAQ
        • Data Security
        • Updates
  • Learn more
    • API Reference
    • Connectors Supported
    • SDK Reference
      • React
      • JS
      • Custom Events
    • Hyperswitch architecture
      • Router
      • Storage
      • A Payments Switch with virtually zero overhead
    • Payment flows
    • Blog
  • Community Guidelines
Powered by GitBook

Compliance

  • Vulnerability Disclosure
  • PCI DSS 4.0
  • ISO 27001:2022

Community

  • Slack
  • Discord
  • GitHub Discussion
On this page
  • 1. Layouts
  • 1.1 Accordion layout
  • 1.2 Tabs layout
  • 2. Wallets
  • 3. Styling variables
  • 4. Rules
  • Tabs
  • Form Inputs
  • Checkbox
  • InputLogo
  • SaveWalletDetailsLabel
  • OrPayUsingLabel
  • OrPayUsingLine
  • TermsTextLabel
  • InfoElement
  • 5. Languages
  • 6. Confirm Button
  • 7. More Configurations
  • Branding
  • Payment Methods Header Text
  • Saved Payment Methods Header Text
  • Custom Message for Card Terms
  • Hide Card Nickname Field
  • Hide Expired Saved Payment Methods
  • Show Card Form by Default
  • Terms
  • Display Saved Payment Methods
  • Display Saved Payment Methods Checkbox
  • Payment Method Order
  • Business
  • Read Only
  • Show Short Surcharge Message
  • Next step:

Was this helpful?

  1. Explore Hyperswitch
  2. Checkout Experience
  3. Customizable and Native Integrations
  4. Web

Customization

Customize your Web unified checkout

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} />
Variable
Description
Values

walletReturnUrl: string

Defines the URL to redirect users to after completing a payment.

This will take a URL string as its value

applePay: showType googlePay: showType payPay: showType klarna: showType

Determines the visibility of Apple Pay, Google Pay, Paypal and Klarna.

showType can take two values:

  • "auto": Display when supported.

  • "never": Always hidden

style: { theme: theme, type: styleType, height: int, buttonRadius: int, }

Configures the wallet's appearance with the following options:

  • theme: Sets the theme.

  • type: Defines the style type (e.g. buy).

  • height: Specifies the height of the wallet.

  • buttonRadius: Adjusts the button corner radius.

theme: It can take values as dark, light, or outline. type: Specifies the wallet button style with options including checkout, pay, buy, installment, default, book, donate, order, addmoney, topup, rent, subscribe, reload, support, tip, and contribute.

3. Styling variables

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

Variable
Description

fontFamily

The font family is used throughout Widgets. Widget supports css fonts and custom fonts by passing the fonts option; reference to elements consumer

fontSizeBase

The font size that's set on the root of the Widget. By default, other font size variables like fontSizeXs or fontSizeSm are scaled from this value using rem units

spacingUnit

The base spacing unit that all other spacing is derived from. Increase or decrease this value to make your layout more or less spacious

borderRadius

The border radius used for tabs, inputs, and other components in the Widget

colorPrimary

A primary color used throughout the Widget. Set this to your primary brand color

colorBackground

The color used for the background of inputs, tabs, and other components in the Widget

colorText

The default text color used in the Widget

colorDanger

A color used to indicate errors or destructive actions in the Widget

fontVariantLigatures

The font-variant-ligatures setting of text in the Widget

fontVariationSettings

The font-variation-settings setting of text in the Widget

fontWeightLight

The font weight used for light text

fontWeightNormal

The font weight used for normal text

fontWeightMedium

The font weight used for medium text

fontWeightBold

The font weight used for bold text

fontLineHeight

The line-height setting of text in the Widget

fontSizeXl

The font size of extra-large text in the Widget. By default this is scaled from var(--fontSizeBase) using rem units

fontSizeLg

The font size of large text in the Widget. By default this is scaled from var(--fontSizeBase) using rem units

fontSizeSm

The font size of small text in the Widget. By default this is scaled from var(--fontSizeBase) using rem units

fontSizeXs

The font size of extra-small text in the Widget. By default this is scaled from var(--fontSizeBase) using rem units

fontSize2Xs

The font size of double-extra small text in the Widget. By default this is scaled from var(--fontSizeBase) using rem units

fontSize3Xs

The font size of triple-extra small text in the Widget. By default this is scaled from var(--fontSizeBase) using rem units

colorSuccess

A color used to indicate positive actions or successful results in the Element

colorWarning

A color used to indicate potentially destructive actions in the Element

colorPrimaryText

The color of text appearing on top of any a var(--colorPrimary) background

colorBackgroundText

The color of text appearing on top of any a var(--colorBackground) background

colorSuccessText

The color of text appearing on top of any a var(--colorSuccess) background

colorDangerText

The color of text appearing on top of any a var(--colorDanger) background

colorWarningText

The color of text appearing on top of any a var(--colorWarning) background

colorTextSecondary

The color used for text of secondary importance. For example, this color is used for the label of a tab that isn’t currently selected

colorTextPlaceholder

The color used for input placeholder text in the Widget

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, .InputLogo, .SaveWalletDetailsLabel, .OrPayUsingLabel, .TermsTextLabel, .InfoElement, .OrPayUsingLine

  • .Tab:focus

  • .Input--invalid, .Label--invalid, .InputLogo--invalid

  • .Input::placeholder

  • .billing-section, .billing-details-text

  • .Input--empty, .InputLogo--empty

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

Class Name
States
Pseudo-Classes
Pseudo-Elements

.Tabs

--selected

:hover, :focus, :active, :disabled

fontSizeBase

--selected

:hover, :focus, :active, :disabled

spacingUnit

--selected

:hover, :focus, :active, :disabled

  • .Tab, .Label, .Input

  • .Tab:focus

  • .Input--invalid, .Label--invalid

  • .Input::placeholder

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.

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

Class Name
States
Pseudo-Classes
Pseudo-Elements

.Label

--empty, --invalid

.Input

--empty, --invalid

:hover, :focus, :disabled, :autofill

::placeholder, ::selection

.Error

Checkbox

Class Name
States
Pseudo-Classes
Pseudo-Elements

.Checkbox

--checked

:hover

.CheckboxLabel

--checked

:hover

.CheckboxInput

--checked

:hover

InputLogo

Class Name
States
Pseudo-Classes
Pseudo-Elements

.InputLogo

:hover

.InputLogo

--invalid

:hover,

.InputLogo

--empty

:hover

SaveWalletDetailsLabel

Class Name
States
Pseudo-Classes
Pseudo-Elements

.SaveWalletDetailsLabel

:hover

OrPayUsingLabel

Class Name
States
Pseudo-Classes
Pseudo-Elements

.OrPayUsingLabel

:hover

OrPayUsingLine

Class Name
States
Pseudo-Classes
Pseudo-Elements

.OrPayUsingLine

:hover

TermsTextLabel

Class Name
States
Pseudo-Classes
Pseudo-Elements

.TermsTextLabel

:hover

InfoElement

Class Name
States
Pseudo-Classes
Pseudo-Elements

.InfoElement

:hover

5. Languages

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.

Variable
Description

buttonBackgroundColor

Sets the background color of the payment button

buttonHeight

Define the height of the payment button

buttonWidth

Specify the width of the payment button

buttonBorderRadius

Adjust the border radius of the payment button for rounded corners

buttonBorderColor

Sets the color of the border surrounding the payment button

buttonTextColor

Define the color of the text displayed on the payment button

buttonTextFontSize

Customize the font size of the text on the payment button

buttonTextFontWeight

Specify the font weight of the text on the payment button

buttonBorderWidth

Specify the border width of the button

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} />;

Show Short Surcharge Message

The showShortSurchargeMessage property allows merchants to display a short message when a surcharge is applied, instead of the default message provided by the SDK.

The short message format will be: Fee: {Currency} {Amount}

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

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

Next step:

Last updated 1 month ago

Was this helpful?

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)
Setup Payment Methods