Documentation Index Fetch the complete documentation index at: https://primer.io/docs/llms.txt
Use this file to discover all available pages before exploring further.
Primer Checkout provides a set of components that work together to create a complete payment experience. This page gives you an overview of all available components and how they relate to each other.
Component Hierarchy
The components follow a hierarchical structure where parent components provide context to their children. Each parent literally contains its children. The spatial nesting mirrors the DOM nesting. The components follow a hierarchical structure where the checkout controller manages presentation components, which in turn contain SDK UI elements. CheckoutSheet
CheckoutHost
The iOS SDK uses a scope-based hierarchy where PrimerCheckout provides a PrimerCheckoutScope, which gives access to payment method-specific scopes.
Core Components
Component Purpose <primer-checkout>Root component that initializes the SDK and provides checkout context <primer-main>Manages checkout states and provides layout customization <primer-payment-method>Renders a specific payment method (card, PayPal, Apple Pay, etc.) <primer-payment-method-container>Container for filtering and organizing multiple payment methods
Checkout controllers Function Returns Purpose rememberPrimerCheckoutController()PrimerCheckoutControllerMain session controller rememberCardFormController()PrimerCardFormControllerCard form state and actions rememberPaymentMethodsController()PrimerPaymentMethodsControllerAvailable payment methods rememberVaultedPaymentMethodsController()PrimerVaultedPaymentMethodsControllerSaved payment methods
Presentation components Component Description API Reference PrimerCheckoutSheetModal bottom sheet checkout Reference PrimerCheckoutHostInline checkout host Reference PrimerCardFormCard payment form Reference PrimerPaymentMethodsPayment method list Reference
Entry points Component Description API Reference PrimerCheckoutRoot SwiftUI view for checkout Reference PrimerCheckoutPresenterUIKit presenter (modal sheet) Reference
Scopes Scope Purpose API Reference PrimerCheckoutScopeTop-level checkout management Reference PrimerPaymentMethodSelectionScopePayment method list and selection Reference PrimerCardFormScopeCard form fields and validation Reference PrimerApplePayScopeApple Pay flow Reference PrimerPayPalScopePayPal flow Reference PrimerKlarnaScopeKlarna multi-step flow Reference PrimerAchScopeACH multi-step flow Reference PrimerWebRedirectScopeWeb redirect flow (e.g., Twint) Reference PrimerFormRedirectScopeForm-based redirect flow (e.g., BLIK, MBWay) Reference PrimerQRCodeScopeQR code flow (e.g., PromptPay) Reference
Component Purpose <primer-card-form>Container that provides context for card inputs <primer-input-card-number>Secure hosted input for card number <primer-input-card-expiry>Secure hosted input for expiry date <primer-input-cvv>Secure hosted input for CVV <primer-input-cardholder-name>Input for cardholder name <primer-card-form-submit>Submit button with built-in loading states <primer-input-label>Label component for card inputs <primer-input-wrapper>Wrapper for styling and layout of inputs <primer-billing-address>Billing address collection form
Defaults objects Object Parent Component Sub-components PrimerCheckoutSheetDefaultsPrimerCheckoutSheetSplash, Loading, Success, Error, PaymentMethodSelection, VaultedMethods, PaymentMethodsCardFormDefaultsPrimerCardFormCardNumberField, ExpiryField, CvvField, CardholderField, CardNetworkField, CountryCodeField, billing fields, SubmitButtonPaymentMethodsDefaultsPrimerPaymentMethodsSectionHeader, Method, EmptyState
State types Type Purpose Values PrimerCheckoutStateCheckout lifecycle Loading, ReadyPrimerCheckoutEventPayment outcomes Success, FailurePrimerCardFormController.StateCard form state Field values, validation, loading
SDK-managed fields PrimerCardFormScope provides ViewBuilder methods that return SDK-managed card fields:Method Purpose PrimerCardNumberFieldSecure card number input with network detection PrimerExpiryDateFieldExpiry date input PrimerCvvFieldCVV/CVC input PrimerCardholderNameFieldCardholder name input PrimerPostalCodeFieldPostal/ZIP code input PrimerCountryFieldCountry selector DefaultCardFormViewComplete default card form layout
State types Type Purpose Key properties PrimerCheckoutStateCheckout lifecycle .initializing, .ready, .success, .failure, .dismissedPrimerCardFormStateCard form state isValid, isLoading, fieldErrors, selectedNetworkPrimerPaymentMethodSelectionStatePayment method list Available payment methods
Field configuration Each card form field can be configured via InputFieldConfig: cardScope. cardNumberConfig = InputFieldConfig (
label : "Card Number" ,
placeholder : "1234 5678 9012 3456" ,
styling : PrimerFieldStyling ( cornerRadius : 8 )
)
Utility Components
Component Purpose <primer-error-message-container>Displays payment error messages <primer-vault-manager>Manages saved payment methods <primer-show-other-payments>Toggle button to show additional payment methods
Theming Class Purpose PrimerThemeRoot theme container LightColorTokensLight mode colors DarkColorTokensDark mode colors SpacingTokensSpacing values TypographyTokensFont styles RadiusTokensCorner radius BorderWidthTokensBorder widths SizeTokensComponent sizes
Theming Struct Purpose PrimerCheckoutThemeRoot theme container ColorOverridesBrand, text, border, and icon colors RadiusOverridesCorner radius values SpacingOverridesSpacing values SizeOverridesComponent sizes TypographyOverridesFont styles and sizes BorderWidthOverridesBorder widths
Type aliases Alias Signature Used for Component() -> any ViewsplashScreen, loadingScreen, submitButtonContainerComponent(@escaping () -> any View) -> any ViewcontainerErrorComponent(String) -> any ViewerrorScreenPaymentMethodItemComponent(CheckoutPaymentMethod) -> any ViewpaymentMethodItemCardFormScreenComponent(any PrimerCardFormScope) -> any ViewCard form screen
Basic Usage
< primer-checkout client-token = "your-client-token" >
< primer-main slot = "main" >
< div slot = "payments" >
<!-- Payment methods appear here -->
< primer-payment-method type = "PAYMENT_CARD" ></ primer-payment-method >
< primer-payment-method type = "PAYPAL" ></ primer-payment-method >
<!-- Error display -->
< primer-error-message-container ></ primer-error-message-container >
</ div >
< div slot = "checkout-complete" >
< h2 > Payment successful! </ h2 >
</ div >
</ primer-main >
</ primer-checkout >
@Composable
fun CheckoutScreen (clientToken: String ) {
val checkout = rememberPrimerCheckoutController (clientToken)
PrimerCheckoutSheet (
checkout = checkout,
onEvent = { event ->
when (event) {
is PrimerCheckoutEvent.Success -> navigateToConfirmation (event.checkoutData)
is PrimerCheckoutEvent.Failure -> {
Log. e ( "Checkout" , "Failed: ${ event.error.description } " )
}
}
},
onDismiss = { navigateBack () },
)
}
struct CheckoutView : View {
let clientToken: String
var body: some View {
PrimerCheckout (
clientToken : clientToken,
primerSettings : PrimerSettings ( paymentHandling : . auto ),
primerTheme : PrimerCheckoutTheme (
colors : ColorOverrides ( primerColorBrand : . blue )
),
onCompletion : { state in
switch state {
case . success ( let result):
print ( "Payment: \( result. payment ?. id ?? "" ) " )
case . failure ( let error):
print ( "Failed: \( error. errorId ) " )
case . dismissed :
print ( "Dismissed" )
default :
break
}
}
)
}
}
How Components Communicate
Components communicate through:
Context inheritance - Child components receive context from their parents (e.g., card inputs receive form context from their parent card form)
Events - Components emit events that you can listen to for state changes
Customization points (Slots on Web, Composable lambdas on Android, Scope closures on iOS) - Allow you to inject custom content at specific points
Customization at Each Level
<primer-checkout> - SDK options, theming, global configuration
<primer-main> - Layout structure through customization points
<primer-payment-method> - Payment method-specific options
<primer-card-form> - Complete control over card form layout and styling
PrimerCheckoutSheet / PrimerCheckoutHost - Presentation mode and event handling
PrimerCheckoutSheetDefaults - Override default screens (splash, loading, success, error)
CardFormDefaults - Customize individual card form fields
PrimerTheme - Colors, typography, spacing, and border radius
PrimerCheckout - Client token, settings, theme, and completion handling
PrimerCheckoutScope - Splash, loading, error screens, and container customization
PrimerPaymentMethodSelectionScope - Payment method list item and screen customization
PrimerCardFormScope - Card form fields, layout sections, and submit button
PrimerCheckoutTheme - Colors, typography, spacing, radius, and border widths
See also
Using Slots Learn how to customize layout with slots
Build a custom card form Step-by-step tutorial for card form customization
Styles Customize appearance with CSS variables
SDK Reference Detailed API documentation for all components