Skip to main content
This page documents all notable changes to Primer Checkout for Android (io.primer:checkout, 3.x). Changes to the 2.x Android SDK (io.primer:android, Drop-in and Headless) are on the Android SDK (legacy) page. Primer Checkout for Android is in beta. The API can still change before the stable release.
2026-10-21
๐Ÿคนโ€โ™€๏ธ Breaking changes
  • PrimerCheckoutState.BeforeClientSessionUpdated and PrimerCheckoutState.ClientSessionUpdated are removed. A client-session update now goes from Ready to a new Ready carrying the updated session. Use PrimerCardFormController.state.isLoading to show progress while the update runs.
  • PrimerTheme takes a new appearanceMode parameter, and borderWidthTokens: BorderWidthTokens is now widthTokens: WidthTokens. Calls that pass theme arguments by position no longer compile.
  • primerColorBackground is renamed primerColorBackgroundPrimary.
  • The raw palette colours (primerColorGray*, primerColorRed*, primerColorBlue*, primerColorGreen*) and the background tokens no view draws with are no longer public. Theme with the semantic tokens instead.
  • primerColorBorderOutlinedHover, primerColorBorderTransparentHover and the base radius, spacing and size tokens are removed.
  • SizeTokens.xxlarge defaults to 40dp instead of 44dp.
๐Ÿš€ New features
  • Google Pay: Express Checkout shipping. PrimerCheckoutController.onShippingAddressChange returns the shipping options for the address the shopper picks in the Google Pay sheet, and onShippingOptionChange confirms the option they select.
  • Google Pay now depends on com.google.android.gms:play-services-wallet 20.0.0 (was 19.5.0).
  • PrimerAppearanceMode (LIGHT, DARK, SYSTEM) on PrimerTheme sets light, dark or system appearance for the whole checkout.
  • New primerColorOnBrand colour for content drawn on the brand colour, such as the pay button label.
  • Card and billing fields offer system autofill.
  • Card form fields and the country field are locked while a payment is in progress.
  • Checkout UI test tags are exposed as resource ids, so UI test tools outside Compose can find them.
๐Ÿ”ง Fixes
  • Changing dark mode, locale or font size during checkout no longer crashes the card form.
  • The SDK no longer re-initialises when the composable that hosts it recomposes.
  • formatAmount works in every state after the first Ready, not only in Ready.
  • Redirect payment methods no longer fail with failed-to-redirect in apps that donโ€™t include Drop-in.
  • Deleting a saved card no longer crashes, and cancelling a delete keeps the selected card.
  • Edit mode on the saved cards list ends when the shopper leaves the list.
  • The amount stays in the payment list title after a failed payment.
  • Every typography setting in the theme is applied, including font weight.
  • Error text follows the bodySmall text style.
  • Colours that ignored the merchantโ€™s theme now use it: vault and back icons, the delete prompt, the Klarna button.
  • NaN and infinite numbers in the theme are ignored instead of breaking the layout.
  • Input fields are 44dp tall, spaced to match the design.
  • The payment method list, the Google Pay button and the Klarna badge match the design, and the Klarna screen shows its title.
  • A card shows the default grey card art until its network is known.
  • The country search field has no floating label.
  • Four billing address placeholders use the same wording as iOS.
  • The pay buttonโ€™s accessibility label reads its visible title.
2026-09-16
๐Ÿš€ New features
  • PrimerCheckoutState.Failure carries checkoutData with the payment id, order id and status when a payment was created.
2026-08-12
Release tooling only. No changes to the SDK.
2026-07-30
๐Ÿš€ New features
  • Google Pay: allowCreditCards and allowPrepaidCards options.
  • Klarna: the bundled Klarna SDK is upgraded to 2.11.x.
  • Payment results carry the payment status.
๐Ÿ”ง Fixes
  • Backend-driven payment methods no longer show a title bar on their redirect web view.
  • Backend-driven payment methods are left out of the list in manual payment handling mode.
2026-07-03
๐Ÿš€ New features
  • onBeforePaymentCreate runs before the SDK creates a payment. Continue or abort the payment, and set an idempotency key for it.
2026-06-25
๐Ÿš€ New features
  • QR code payment methods.
  • Backend-driven payment methods with dynamic forms and redirects.
  • PrimerCardFormController exposes BIN data for the card being entered.
  • An idempotency key can be set for payments.
  • orderedAllowedCardNetworks and cvvLabel on the card network descriptor.
  • The sheet and inline checkout share one implementation.
๐Ÿ”ง Fixes
  • Theme textColor and dark mode surfaces are applied, and the card surface in dark mode matches iOS.
  • JavaScript sandbox errors are handled instead of failing the checkout.
  • Navigation-step controllers are no longer part of the public API.
2026-03-19
๐Ÿคนโ€โ™€๏ธ Breaking changes
  • The package namespace changed from io.primer.android.components to io.primer.checkout. Update your imports.
2026-03-12
First public beta of Primer Checkout for Android, a Jetpack Compose-native SDK. Requires API 24+, Kotlin 2.0+ and Jetpack Compose. Ships the card form, the payment method list, saved payment methods with CVV recapture, translations and accessibility support.