Branding, language, and form options

Build a theme in the dashboard

Open Settings → Pay Playground after your organization has access. Choose Test donations, configure the pop-up, and copy the generated integration snippet. Replace its key placeholder with your matching publishable key from Pay SDK Keys. Selecting Live donations changes the key placeholder; it does not switch your account’s processing mode by itself. To start with a saved organization theme, select Load organization themes, choose a theme, and select Use this theme. This prefills supported colors, control styles, fonts, and logo. Loading themes requires theme-read permission. The pop-up theme is a copy you can customize independently. Editing it does not modify the saved organization theme, and later changes to the source theme do not automatically change your copied configuration.

Apply a theme in code

Pass theme to mountButton() or open():

const popupTheme = {
  mode: 'auto',
  radius: '10px',
  inputRadius: '6px',
  buttonRadius: '999px',
  popupRadius: '16px',
  font: 'Inter, system-ui, sans-serif',
  fontUrl: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap',
  logo: {
    light: 'https://giving.example.org/assets/logo-dark.svg',
    dark: 'https://giving.example.org/assets/logo-light.svg',
  },
  light: {
    brand: '#245c48', brandFg: '#ffffff',
    bg: '#ffffff', surface: '#f3f6f4', text: '#17251e',
  },
  dark: {
    brand: '#93d4b8', brandFg: '#10291d',
    bg: '#15231c', surface: '#1c3025', text: '#f5faf7',
  },
  copy: {
    title: 'Support lasting change',
    subtitle: 'Your generosity makes our work possible.',
    action: 'Give',
  },
  locale: 'en',
  showLocalePicker: true,
  paymentMethods: { allowCard: true, allowBank: true },
  billing: { fields: 'full' },
};

pay.mountButton('#donate', {
  amount: 5000,
  label: 'Give today',
  theme: popupTheme,
});

Replace image URLs with publicly accessible HTTPS assets. logo and avatar accept either a single URL or an object containing light and dark URLs. avatar supplies the fallback image for the donor’s giving-profile chip. mode accepts light, dark, or auto. A fixed mode hides the theme toggle; auto lets the donor switch. Unspecified tokens use the pop-up defaults. Define both light and dark tokens when supporting both appearances. font is a CSS font stack. To load a webfont, supply its HTTPS stylesheet in fontUrl; a font-family name alone does not download a font. Your organization is responsible for using licensed fonts and accessible colors.

Color and shape reference

Set color tokens separately inside theme.light and theme.dark:

Tokens	Surface
`brand`, `brandHover`, `brandFg`, `brandSoft`	Accent, hover accent, text on the accent, and soft accent backgrounds
`bg`, `surface`	Main and secondary backgrounds
`text`, `textMuted`, `textPlaceholder`	Main, secondary, and placeholder text
`border`, `borderMuted`, `focus`	Borders, dividers, and focus indication
`inputBg`, `inputDisabledBg`, `inputText`	Input backgrounds and text
`inputBorder`, `inputFocus`, `inputPlaceholder`	Input borders, focus, and placeholder color
`buttonBg`, `buttonHover`, `buttonText`	Button-specific colors

Use theme.radius for shared rounding, or inputRadius, buttonRadius, and popupRadius for separate control shapes. Values are CSS lengths such as 8px or 0.5rem.

Style the launch button

Button options are separate from the full pop-up theme:

Option	Behavior
`label`	Required button text
`logo`	Override the button’s organization image
`hideLogo`	Hide the leading image or organization mark
`brand.color`, `brand.foreground`	Button background and text colors; also provide simple pop-up branding
`brand.radius`, `brand.font`	Button radius and font; simple pop-up defaults
`className`	Your host-page CSS classes; replaces the automatic button styling
`theme`	Detailed pop-up appearance; takes precedence over overlapping simple brand values inside the pop-up

Your page must provide the CSS for any classes you pass. Host-page CSS does not reach inside the hosted pop-up or Payframes. For a fully custom launch button, render your own element and call pay.open().

Languages and copy

Built-in theme.locale values are en, es, fr, de, pt, nl, and it. If omitted, the pop-up uses a supported browser language, falling back to English. Set showLocalePicker: true to let donors change languages in checkout. Use theme.copy.title, subtitle, and action for prominent checkout copy. action is the verb used in the amount-bearing donation button. Use theme.strings to override individual labels. Overrides take precedence over built-in translations, so a fixed custom string is not automatically translated when the donor changes language.

const languageOptions = {
  locale: 'es',
  strings: {
    continueAction: 'Continuar',
    receiptHeadline: '¡Gracias por tu generosidad!',
    receiptPending: 'Tu donación está pendiente de confirmación.',
  },
};

These are the available string override keys:

Area	Keys
Sign-in and navigation	`emailHeadingLogin`, `emailHeadingSignup`, `verifyHeading`, `resendCode`, `verifying`, `continueAction`
Giving profile	`givingAsHeader`, `giveAsHeader`, `addNewProfile`, `addProfile`
Payment methods	`paymentMethodHeader`, `paymentMethodsHeader`, `addPaymentMethod`, `saveCard`, `saveBank`, `saveAccount`, `saving`, `cancel`
Completion	`receiptHeadline`, `receiptPending`, `receiptScheduled`, `receiptSubtitle`
Footer and disclosure	`securityNote`, `termsLink`, `privacyLink`, `recaptchaDisclosure`, `recaptchaPrivacyLabel`, `recaptchaTermsLabel`
Validation	`fieldRequired`, `errorCardNumber`, `errorCardExpiration`, `errorCardCvv`, `errorCardDetails`, `errorBillingAddress`, `errorRoutingNumber`, `errorRoutingChecksum`, `errorAccountNumber`, `errorTransitNumber`, `errorInstitutionNumber`, `errorGeneric`, `errorFormLoading`

If overriding recaptchaDisclosure, retain both {privacy} and {terms} placeholders so their disclosure links remain present. Localized copy changes presentation; it does not change payment eligibility, currency, or legal terms.

Donor and payment-form options

Option	Default	Effect
`theme.signup.allowCompany`	`false`	Offer a company giving profile during signup
`theme.signup.companyLabel`	Built-in label	Customize the company option’s wording
`theme.signup.allowGuest`	`false`	Offer guest checkout without remembering the donor’s sign-in session
`theme.signup.guestLabel`	Built-in label	Customize the guest option’s wording
`theme.paymentMethods.allowCard`	`true`	Show card entry where supported
`theme.paymentMethods.allowBank`	`true`	Show bank entry where supported
`theme.paymentMethods.allowBankLogin`	`false`	Show bank-login connection when configured for your account
`theme.billing.fields`	`full`	Use `full` address collection or `minimal` name and postal-code collection

Payment-method options control the entry UI; they do not enable a processor or add account capabilities. Keep at least one supported method available. Confirm minimal billing is appropriate for your processor. Guest mode does not bypass payment verification or fraud checks.

Organization brand versus appearance

Use organizationBrandId in the donation options to identify the donation’s financial brand. Set theme to control how checkout looks. A theme, logo, or language selection does not select an organization, financial brand, processing currency, or payment processor. The publishable key identifies your organization.

​Build a theme in the dashboard

​Apply a theme in code

​Color and shape reference

​Style the launch button

​Languages and copy

​Donor and payment-form options

​Organization brand versus appearance