Card Payment visual customizations
The mobile checkout flow via Card Payment was built in a modular way. Its foundation follows UX best practices to give the buyer the best experience without you having to worry about design details.
When you want to align the checkout with your app's identity, the SDK uses tokenized components in atomic design: changing a token is automatically reflected across components, screens, and states.
All visual customization starts from MPCheckoutAppearance, which you pass to the checkout Builder. It defines the applied theme (theme) and how the app switches between light and dark modes (style).
data class MPCheckoutAppearance(
val theme: MercadoPagoThemeConfiguration = MercadoPagoThemes.Default,
val style: MercadoPagoUserInterfaceStyle = MercadoPagoUserInterfaceStyle.System,
)| Parameter | Description | Example |
theme: MercadoPagoThemeConfiguration | Set of light and dark themes that define the token values. Without customization, it uses MercadoPagoThemes.Default. | myTheme |
style: MercadoPagoUserInterfaceStyle | How the app switches between themes: dark only, light only, or following the device. | MercadoPagoUserInterfaceStyle.System |
A theme is a set of tokens grouped by category. Each mode — light and dark — is a MercadoPagoThemeProvider, where you define the value of each category. It is what fills the theme of MPCheckoutAppearance.
val lightTheme = MercadoPagoThemeProvider.Default(
color = lightColors,
spacing = lightSpacings,
radius = lightRadius,
borderWidth = lightBorderWidth,
shape = lightShape,
typography = lightTypography,
)| Token | Description | Example |
color: MercadoPagoColor | Colors of components, screens, backgrounds, etc. | lightColors |
spacing: MercadoPagoSpacing | Spacing. | lightSpacings |
radius: MercadoPagoRadius | Border radii. | lightRadius |
borderWidth: MercadoPagoBorderWidth | Border widths. | lightBorderWidth |
shape: MercadoPagoShape | Component shapes. | lightShape |
typography: MercadoPagoTypography | Typography. | lightTypography |
You build a MercadoPagoThemeConfiguration — with one provider for light mode and another for dark mode — and assign it to the theme of MPCheckoutAppearance. You can create a full theme or start from the default theme and override only what you need.
| Approach | When to use it |
| Full theme | You define all the theme tokens. |
| Override tokens | You start from the default theme and change only the tokens you need. |
Full theme:
val myTheme = MercadoPagoThemeConfiguration(
lightTheme = lightTheme,
darkTheme = darkTheme,
)
val appearance = MPCheckoutAppearance(theme = myTheme)Override tokens — start from the default theme with copy:
val myTheme = MercadoPagoThemeConfiguration(
lightTheme = MercadoPagoDefaultLightTheme.copy(
color = lightColors
),
darkTheme = MercadoPagoDefaultDarkTheme.copy(
color = darkColors
)
)