Checkout customization

When you call createCheckout(), the SDK renders a complete payment UI inside your container. Learn what the default checkout includes and how to customize it.

Default styles

Out of the box, createCheckout() applies the default CSS styles and renders:

An accordion with radio-button selection between available payment methods.
A card form with Card number, Expiration date, and Security code fields, plus the optional fields described in Card form. The form’s submit button reads Continue.
PayPal, Google Pay, and Apple Pay buttons in their own accordion sections. When Apple Pay is available, the checkout leaves out Google Pay.
Loading spinners, error containers, and a success screen.
A responsive layout with a mobile breakpoint at 768 px.

The accordion auto-selects the first available payment method and expands it. To customize the default UI, follow the sections below.

Override CSS

The default checkout renders elements with .ff-* CSS classes you can target for visual overrides:

Class	Purpose
`.ff-skin-default`	Top-level container (max-width: 400px, centered)
`.ff-payment-method-card`	Payment method card (hidden until `.visible`)
`.ff-payment-method-card.expanded`	Accordion expanded state
`.ff-payment-method-radio`	Custom radio button
`.ff-payment-method-label`	Row with radio button and header
`.ff-payment-method-content`	Animated accordion panel
`.ff-card-form-container`	Card form wrapper
`.ff-card-form-submit-button`	Submit button
`.ff-card-form-label`	Input labels
`.ff-card-form-text-input`	Native inputs (cardholder, email, zip code) and the country selector
`.ff-card-form-text-input.error`	Error state for native inputs
`.ff-card-form-select`	Country selector
`.ff-select-arrow`	Country selector arrow
`.card-form-row`	Row with the expiration date and security code
`.errorContainer`	Error text under each card form field
`.ff-security-message`	Security message below forms
`.ff-payment-features`	Checkmark list per payment method
`.payment-errors-container`	Error message area
`.loader-container`	Full overlay with loading spinner
`.ff-sdk-loader-container`	Loading spinner while the checkout initializes
`.ff-sdk-error-container`	Message shown when the checkout fails to initialize

For example, to change the submit button border radius:

.ff-card-form-submit-button {
  border-radius: 8px;
}

Custom layout

To place the card form and each payment button in your own layout, render them one by one with Billing.initMethod(). Each call renders one payment method into an element you choose.

Payment method order

The paymentMethodOrder array controls the display order of payment methods in the checkout accordion. By default, it shows: APPLE_PAY > GOOGLE_PAY > PAYPAL > PAYMENT_CARD.

await Billing.createCheckout({
  // ...required options
  paymentMethodOrder: [
    'APPLE_PAY',
    'GOOGLE_PAY',
    'PAYPAL',
    'PAYMENT_CARD',
  ],
});

Omit a method from the array to exclude it from the checkout. For example, to show only card and PayPal:

paymentMethodOrder: ['PAYMENT_CARD', 'PAYPAL'],

Card form

The card form always shows the card number, expiration date, and security code. The fields below are optional. The card option applies to both createCheckout() and Billing.initMethod().

Cardholder name field

Set card.cardholderName.required:

true: Show and require the field.
false: Hide the field.
Unset: Follow show_cardholder_name_field in Checkout page fields.

await Billing.createCheckout({
  // ...required options
  card: {
    cardholderName: {
      required: true,
    },
  },
});

Email address field

Set card.emailAddress.visible:

true: Show an email input pre-filled with customer.email.
false: Hide the field.
Unset: Follow show_email_field in Checkout page fields.

The SDK checks that the email is valid. It sends the email with the payment only when the buyer changes it from customer.email. Use template to format that email before the SDK sends it. Any occurrence of {{email}} is replaced with the email the buyer entered.

await Billing.createCheckout({
  // ...required options
  card: {
    emailAddress: {
      visible: true,
      template: '{{email}}',
    },
  },
});

Country and zip code

The card form shows a Country selector and a Zip code field when your organization collects the customer’s location. Turn them on in Checkout page fields or with Collect the customer’s location on the payment form in Taxes. There’s no SDK option for these fields.

Country: Lists the countries FunnelFox Payments returns, with the buyer’s country detected from their IP selected. Without a list, the field shows the detected country and can’t be changed.
Zip code: Shown for the countries where your settings require it, and required when shown. It updates when the buyer switches country.

The SDK sends the country and zip code with the payment. When FunnelFox Payments Taxes is on, changing either one recalculates tax. Learn more about taxes in the Web SDK.

Field validation

The card form shows errors the same way as Stripe’s payment form:

Impossible card number: Shown while the buyer types.
Incomplete or invalid value: Shown after the buyer leaves the field and hidden while they retype it. An error stays visible when the buyer comes back to the field, until they start typing.
Empty field: Shown after the buyer submits the form.

The error text appears under the field in .errorContainer, in #df1b41 at 15px.

Payment button

Each payment button accepts styling options that are passed to the payment provider SDK.

createCheckout() uses the default PayPal and Google Pay buttons and a black Apple Pay button. There, you can set only the Apple Pay buttonType. All options below apply to Billing.initMethod().

Apple Pay

Set the button color with buttonStyle: 'black' (default), 'white', or 'white-outline'. Set the button text with buttonType.

await Billing.initMethod(PaymentMethod.APPLE_PAY, element, {
  // ...required options
  applePay: {
    buttonStyle: 'black', // 'black' | 'white' | 'white-outline'
    buttonType: 'continue',
  },
});

`buttonType` values	How the SDK renders them
`'plain'`, `'buy'`, `'set-up'`, `'donate'`, `'check-out'`, `'book'`, `'subscribe'`	Through Primer
`'add-money'`, `'continue'`, `'contribute'`, `'order'`, `'pay'`, `'reload'`, `'rent'`, `'support'`, `'tip'`, `'top-up'`	With Apple’s own Apple Pay button

For the second group, the SDK loads Apple’s Apple Pay script from applepay.cdn-apple.com and places Apple’s button over Primer’s button. The payment still runs through Primer. The button uses the browser’s language and a 28 px corner radius. If Apple’s script fails to load or doesn’t create the button within 4 seconds, the SDK shows Primer’s plain Apple Pay button instead. If your page uses a Content Security Policy, allow applepay.cdn-apple.com in script-src.

PayPal

Customize the PayPal button appearance and payment flow.

Option	Values	Default
`buttonColor`	`'gold'`, `'blue'`, `'silver'`, `'black'`, `'white'`	`'gold'`
`buttonShape`	`'pill'`, `'rect'`	`'pill'`
`buttonLabel`	`'pay'`, `'checkout'`, `'buynow'`, `'paypal'`	`'pay'`
`buttonSize`	`'small'`, `'medium'`, `'large'`	`'large'`
`buttonHeight`	Pixel value	`54`
`paymentFlow`	`'PREFER_VAULT'`, `'DEFAULT'`	`'PREFER_VAULT'`

await Billing.initMethod(PaymentMethod.PAYPAL, element, {
  // ...required options
  paypal: {
    buttonColor: 'gold',
    buttonShape: 'pill',
    buttonLabel: 'pay',
    buttonSize: 'large',
    buttonHeight: 54,
    paymentFlow: 'PREFER_VAULT',
  },
});

Google Pay

Customize the Google Pay button appearance and sizing.

Option	Values	Default
`buttonColor`	`'black'`, `'white'`	`'black'`
`buttonSizeMode`	`'fill'`, `'static'`	`'fill'`
`buttonType`	`'pay'`, `'book'`, `'buy'`, `'checkout'`, `'donate'`, `'order'`, `'plain'`, `'subscribe'`	`'pay'`

await Billing.initMethod(PaymentMethod.GOOGLE_PAY, element, {
  // ...required options
  googlePay: {
    buttonColor: 'black',
    buttonSizeMode: 'fill',
    buttonType: 'pay',
  },
});

Card input

Card number, expiry, and CVV fields are rendered inside iframes by the payment provider, so regular CSS cannot reach them. Use the style option to control their appearance:

await Billing.createCheckout({
  // ...required options
  style: {
    input: {
      base: {
        borderWidth: '1px',
        borderStyle: 'solid',
        borderColor: 'rgb(0 0 0 / 10%)',
        height: '36px',
        paddingHorizontal: 10,
        borderRadius: '6px',
      },
      error: {
        borderColor: 'rgb(227, 47, 65)',
      },
    },
  },
});

The base object also supports fontSize, color, fontFamily, and fontWeight. By default, SDK applies the following styles:

Property	Base state	Error state
`borderWidth`	`'1px'`	—
`borderStyle`	`'solid'`	—
`borderColor`	`'rgb(0 0 0 / 10%)'`	`'rgb(227, 47, 65)'`
`height`	`'36px'`	—
`paddingHorizontal`	`10`	—
`borderRadius`	`'6px'`	—

The cardholder name, email, and zip code inputs and the country selector are native HTML elements. Style them with CSS using the .ff-card-form-text-input class, not through the style option.

API reference

Webhook reference

Billing Web SDK

Checkout customization

Default styles

Override CSS

Custom layout

Payment method order

Card form

Cardholder name field

Email address field

Country and zip code

Field validation

Payment button

Apple Pay

PayPal

Google Pay

Card input

​Default styles

​Override CSS

​Custom layout

​Payment method order

​Card form

​Cardholder name field

​Email address field

​Country and zip code

​Field validation

​Payment button

​Apple Pay

​PayPal

​Google Pay

​Card input

Default styles

Override CSS

Custom layout

Payment method order

Card form

Cardholder name field

Email address field

Country and zip code

Field validation

Payment button

Apple Pay

PayPal

Google Pay

Card input