Skip to content

Customization

Match the Cardencer checkout to your brand: layouts, themes, styling variables, CSS rules, wallets, languages and the pay button.

The payment form is designed to convert out of the box, but you control how it looks and behaves. Appearance options go into hyper.widgets({ clientSecret, appearance }); behaviour options go into widgets.create("payment", options) (or the options prop of PaymentElement in React).

Layouts#

Two layouts are available. The default is accordion.

const options = {
  layout: {
    type: "accordion",
    defaultCollapsed: false,
    radios: true,
    spacedAccordionItems: false,
  },
};

You can also pass the layout as a string: layout: "tabs".

Saved cards#

Returning customers see their saved cards first. hideCardExpiry: true hides the expiry date on saved cards and puts the CVC input inline:

js
const options = {
  layout: { savedMethodCustomization: { groupingBehavior: "groupByPaymentMethods", hideCardExpiry: true } },
};

Apple Pay and Google Pay placement#

One-tap wallets appear above the form by default. Set displayOneClickPaymentMethodsOnTop: false to show them inside the layout instead:

js
const options = { layout: { type: "tabs", displayOneClickPaymentMethodsOnTop: false } };

Wallets#

js
const options = {
  wallets: {
    walletReturnUrl: "https://example.com/checkout/complete",
    applePay: "auto",
    googlePay: "auto",
    style: { theme: "dark", type: "buy", height: 48, buttonRadius: 8 },
  },
};
Option Values
walletReturnUrl URL the customer returns to after a wallet payment. Required for wallets.
applePay, googlePay "auto" shows the button when the device supports it; "never" hides it.
style.theme dark, light or outline.
style.type Button label: default, buy, pay, checkout, book, donate, order, subscribe, tip and more.
style.height, style.buttonRadius Size and corner radius in pixels.

Themes and variables#

Start from a theme, then override variables:

js
const appearance = {
  theme: "default", // "default", "midnight", "brutal", "charcoal", "soft" or "none"
  variables: {
    fontFamily: "Inter, system-ui, sans-serif",
    fontSizeBase: "16px",
    colorPrimary: "#4E6ADD",
    colorBackground: "#ffffff",
    colorText: "#0a0b0d",
    colorDanger: "#d92d20",
    borderRadius: "10px",
    spacingUnit: "4px",
  },
};
const widgets = hyper.widgets({ clientSecret, appearance });
Variable Controls
fontFamily, fontSizeBase, fontWeightNormal, fontWeightBold, fontLineHeight Typography. Other font sizes scale from fontSizeBase.
colorPrimary, colorPrimaryText Brand colour and the text on top of it.
colorBackground, colorText, colorTextSecondary, colorTextPlaceholder Inputs, tabs and text.
colorDanger, colorSuccess, colorWarning States.
borderRadius, spacingUnit Shape and density.

Rules#

rules maps CSS-like selectors to CSS properties (camelCase) for fine-grained control:

js
const appearance = {
  theme: "default",
  rules: {
    ".Tab": { border: "1px solid #e4e4e7", boxShadow: "none" },
    ".Tab:hover": { borderColor: "#4E6ADD" },
    ".Input": { padding: "12px 14px" },
    ".Input--invalid": { borderColor: "#d92d20" },
    ".Label": { fontWeight: "600" },
  },
};

Supported classes include .Tab, .Label, .Input, .InputLogo, .TermsTextLabel, .InfoElement and .OrPayUsingLabel, with states such as --invalid and --empty and pseudo-classes such as :hover and :focus.

Languages#

The form uses the customer's browser language when it is supported and falls back to English. To force a language, pass locale:

js
const widgets = hyper.widgets({ clientSecret, appearance, locale: "fr" });

Supported locales: ar, ca, de, en, en-GB, es, fr, fr-BE, he, it, ja, nl, pl, pt, ru, sv, zh.

Pay button#

If the SDK renders the pay button (sdkHandleConfirmPayment.handleConfirm: true), style it through appearance.variables:

Variable Controls
buttonBackgroundColor, buttonTextColor Colours.
buttonHeight, buttonWidth Size.
buttonBorderRadius, buttonBorderColor, buttonBorderWidth Border.
buttonTextFontSize, buttonTextFontWeight Label.

More options#

js
const options = {
  branding: "never",
  paymentMethodsHeaderText: "Pay with",
  savedPaymentMethodsHeaderText: "Your saved cards",
  displaySavedPaymentMethods: true,
  displaySavedPaymentMethodsCheckbox: true,
  savedPaymentMethodsCheckboxCheckedByDefault: false,
  hideCardNicknameField: true,
  hideExpiredPaymentMethods: true,
  paymentMethodOrder: ["card"],
  business: { name: "Atelier Martin" },
  readOnly: false,
};
Option Effect
branding "never" hides the SDK branding; "always" shows it.
paymentMethodsHeaderText, savedPaymentMethodsHeaderText Section headings.
displaySavedPaymentMethods Show the customer's saved cards.
displaySavedPaymentMethodsCheckbox Show the "save card" checkbox (needed to save cards).
savedPaymentMethodsCheckboxCheckedByDefault Pre-tick the checkbox.
hideCardNicknameField Hide the card nickname input when saving.
hideExpiredPaymentMethods Hide expired saved cards.
paymentMethodOrder Order of payment methods.
business.name Business name used in the card terms text. Defaults to your merchant name.
readOnly Disable all interaction, for example while you recalculate the basket.

Card terms message#

Replace or hide the text shown under the card form, which is also used as the label of the "save card" checkbox:

js
const options = {
  paymentMethodsConfig: [
    {
      paymentMethod: "card",
      paymentMethodTypes: [
        { paymentMethodType: "credit", message: { displayMode: "custom_message", value: "Your card is saved securely for your next order." } },
        { paymentMethodType: "debit", message: { displayMode: "hidden" } },
      ],
    },
  ],
};

displayMode is default_sdk_message, custom_message or hidden.