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,
},
};const options = {
layout: {
type: "tabs",
paymentMethodsArrangementForTabs: "grid", // "default" puts extra methods in a dropdown
},
};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:
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:
const options = { layout: { type: "tabs", displayOneClickPaymentMethodsOnTop: false } };Wallets#
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:
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:
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:
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#
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:
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.