Step-by-step guide to creating and customizing your own card payment form with Primer Checkout.
This tutorial walks you through building a custom card form with Primer Checkout. You’ll learn how to customize the layout, style the inputs, handle events, and avoid common pitfalls.
Understanding of PrimerCardForm and its @ViewBuilder slots for card form control
Understanding the card form architecture
Web
Android
iOS
The <primer-card-form> component provides a customizable card payment interface with PCI-compliant hosted inputs. Here’s how the components relate to each other:
Security by designThe card input components (primer-input-card-number, primer-input-card-expiry, primer-input-cvv) render secure iframes that isolate sensitive card data. This means:
Card data never touches your page’s DOM
Your integration remains PCI-compliant
Styling is applied through CSS variables that are passed to the iframe
Key components
Component
Purpose
primer-card-form
Container that provides context for all 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-card-holder-name
Input for cardholder name (optional)
primer-card-form-submit
Submit button with built-in loading states
The PrimerCardFormController gives you full control over the card form. You create the controller, observe its state, and build your own UI with custom TextField inputs bound to the controller.
Key state properties
Property
Type
Description
data
Map<PrimerInputElementType, String>
Current field values
fieldErrors
List<SyncValidationError>?
Validation errors per field
isFormValid
Boolean
Whether all required fields pass validation
isLoading
Boolean
Whether a submission is in progress
PrimerCardForm is a SwiftUI view that gives you full control over the card form through three @ViewBuilder section slots: cardDetails, billingAddress, and submitButton. Each slot receives a PrimerCardFormSession, which publishes the form state and exposes the field-update and submit() methods. Compose your layout from the CardFormDefaults per-field building blocks (cardNumber, expiryDate, cvv, cardholderName). Primer handles validation, formatting, and PCI compliance.
Key state properties
The session exposes its state through session.state, a PrimerCardFormState:
Property
Type
Description
isValid
Bool
Whether all required fields pass validation
isLoading
Bool
Whether a submission is in progress
fieldErrors
[FieldError]
Validation errors per field
data
FormData
Current field values keyed by PrimerInputElementType. The card number is masked to its first six and last four digits, for example 424242••••••4242. A number of 10 digits or fewer keeps only the last four. The CVV is always empty
Step 1: Create the card form
Web
Android
iOS
Start by creating a custom card form using the card-form-content slot:
Component hierarchy mattersAll card input components must be nested inside <primer-card-form>. Placing them outside breaks the context connection and the form won’t work.
Create a PrimerCardFormController inside a PrimerCheckoutHost. The controller manages field values, validation, and submission.
@Composablefun CustomCardFormScreen(clientToken: String) { val checkout = rememberPrimerCheckoutController(clientToken) val checkoutState by checkout.state.collectAsStateWithLifecycle() LaunchedEffect(checkoutState) { when (val s = checkoutState) { is PrimerCheckoutState.Success -> { /* navigate */ } is PrimerCheckoutState.Failure -> { /* log error */ } else -> Unit } } when (checkoutState) { is PrimerCheckoutState.Loading -> CircularProgressIndicator() is PrimerCheckoutState.Ready -> { PrimerCheckoutHost(checkout = checkout) { val cardFormController = rememberCardFormController(checkout) CustomCardForm(cardFormController) } } }}
Hold a PrimerCheckoutSession as a @StateObject and place a PrimerCardForm inside a view that has the .primerCheckoutSession(_:theme:onCompletion:) modifier applied. PrimerCardForm resolves its PrimerCardFormSession from the environment, so it works inline anywhere under the modifier.
struct CustomCardFormScreen: View { @StateObject private var session: PrimerCheckoutSession init(clientToken: String) { _session = StateObject(wrappedValue: PrimerCheckoutSession(clientToken: clientToken)) } var body: some View { ScrollView { PrimerCardForm() } .primerCheckoutSession(session) { state in // Handle .success, .failure and .dismissed } }}
Session resolution mattersPrimerCardForm and its slots resolve the active PrimerCardFormSession from the environment. Place the form inside a view that has the .primerCheckoutSession(_:theme:onCompletion:) modifier applied, or the form renders an empty placeholder.
Step 2: Customize the layout
Web
Android
iOS
Vertical layout (default)
Stack inputs vertically for a clean, mobile-friendly form:
Observe form state and bind each OutlinedTextField to the controller’s update methods. The controller handles formatting (card number grouping, expiry date slashes) internally.
Override the cardDetails slot and recompose the form from the CardFormDefaults per-field building blocks. Each block keeps the SDK’s formatting, validation, and inline error display, and is self-hiding when its field is not part of the active configuration.
CardFormDefaults.cardNumber(session) keeps the co-badged network selector inside the card number field, so a recomposed layout handles co-badged cards without extra work. Do not add CardFormDefaults.cardNetwork(session) next to it, or two selectors appear. The submit button stays at its default CardFormDefaults.submitButton unless you also override the submitButton slot.
Step 3: Style the inputs
Web
Android
iOS
Style card inputs using CSS variables. These properties are passed through to the secure iframes:
Handle validation errors by extracting error messages from fieldErrors to display under each field:
private fun hasFieldError( state: PrimerCardFormController.State, type: PrimerInputElementType,): Boolean { return state.fieldErrors?.any { it.inputElementType == type } == true}private fun fieldErrorText( state: PrimerCardFormController.State, type: PrimerInputElementType,): (@Composable () -> Unit)? { val error = state.fieldErrors?.firstOrNull { it.inputElementType == type } return error?.let { { Text(it.errorId) } }}
Validation errors appear after the user leaves a field (on blur), not while typing. The SDK handles this timing internally.
Field visual styling is theme-driven. Pass a PrimerCheckoutTheme to the session and the CardFormDefaults fields pick up its design tokens (colors, spacing, typography, and shape) automatically — there is no per-field styling struct.
Validation errors appear automatically beneath each field. The SDK handles error timing — errors show after the user leaves a field, not while typing. For the full list of design tokens, see the PrimerCheckoutTheme reference.
Step 4: Handle events and submission
Web
Android
iOS
Listen for events to provide feedback and handle the payment flow:
const cardForm = document.querySelector('primer-card-form');// Handle validation errorscardForm.addEventListener('primer:card-error', (event) => { const { inputType, error } = event.detail; console.log(`Error in ${inputType}: ${error.message}`); // Show error feedback to user showFieldError(inputType, error.message);});// Handle successful validationcardForm.addEventListener('primer:card-success', (event) => { const { inputType } = event.detail; console.log(`${inputType} is valid`); // Clear any previous error clearFieldError(inputType);});
For comprehensive event handling patterns, see the Events guide.
Programmatic submission
You can submit the card form programmatically instead of using the built-in submit button:
If you collect the cardholder name elsewhere (e.g., from a shipping form), you can set it programmatically:
const cardForm = document.querySelector('primer-card-form');// Set cardholder name from your formconst name = document.getElementById('shipping-name').value;cardForm.setCardholderName(name);
When using setCardholderName(), you don’t need to include the <primer-input-card-holder-name> component in your form.
Focusing the form
The SDK never moves focus into the card form on its own. When the form is revealed by your UI, for example behind a “Pay with a new card” toggle, focus it once it is visible:
const cardForm = document.querySelector('primer-card-form');showCardSection();cardForm.focus(); // first field in render order
To target one input, call focus() on it directly, for example document.querySelector('primer-input-card-number').focus(). In any layout, primer.cardForm?.focus() from the primer:ready instance does the same, which is the only way to reach the form when the SDK renders it inside its own UI.
Call controller.submit() to tokenize the card data. Disable the button when the form is invalid or a submission is in progress:
While a payment runs (session.state.isLoading is true), the SDK disables the card and billing address fields you compose from CardFormDefaults. It ignores further submit() calls, so a double tap starts only one payment. It ignores session.cancel() until the payment ends, because a running payment cannot be stopped.
Pre-filling cardholder name
If you already know the name, pre-fill it from the session. Keep CardFormDefaults.cardholderName(session) in your layout. The form becomes valid only after the SDK’s cardholder name field validates the value. A name set without the field leaves session.state.isValid false.
session.updateCardholderName("Jane Doe")
When billing fields come entirely from your own data, replace the billingAddress slot. Return EmptyView(), or compose only the CardFormDefaults billing building blocks you want. Then push the values through the session’s update* methods. Keep the card field building blocks (cardNumber, expiryDate, cvv, cardholderName) in your layout: session.state.isValid only becomes true after each of them has validated its value. The billing address is sent with the payment only when a postal code is set.
Step 5: Handle payment completion
Web
Android
iOS
Listen for the checkout state to handle successful payments:
const checkout = document.querySelector('primer-checkout');checkout.addEventListener('primer:state-change', (event) => { const state = event.detail; if (state.isSuccessful) { // Payment completed successfully showSuccessMessage(); redirectToConfirmation(); } if (state.paymentFailure) { // Payment failed showErrorMessage(state.paymentFailure.message); }});
Handle payment outcomes by observing checkout.state:
val state by checkout.state.collectAsStateWithLifecycle()LaunchedEffect(state) { when (val s = state) { is PrimerCheckoutState.Success -> { Log.d("Checkout", "Payment ID: ${s.checkoutData.payment.id}") } is PrimerCheckoutState.Failure -> { Log.e("Checkout", "Diagnostics: ${s.primerError.diagnosticsId}") } else -> Unit }}PrimerCheckoutHost(checkout = checkout) { // Card form content}
Use the onCompletion closure on the .primerCheckoutSession(_:theme:onCompletion:) modifier to handle the checkout outcome. Once the checkout is ready, .failure arrives once per failed attempt and the form stays usable so the shopper can retry. .success or .dismissed ends the session and arrives once. A .failure while the session is still initializing also ends it:
ScrollView { PrimerCardForm()}.primerCheckoutSession(session) { state in switch state { case let .success(result): print("Payment ID: \(result.paymentId)") case let .failure(error, _): print("Error: \(error.localizedDescription)") case .dismissed: break default: break }}
Common mistakes to avoid
Web
Android
iOS
Duplicate card forms
Don’t include both <primer-card-form> and <primer-payment-method type="PAYMENT_CARD"> in your layout. The payment method component already renders a card form internally.
<!-- WRONG: Duplicate card forms --><div slot="payments"> <primer-card-form>...</primer-card-form> <primer-payment-method type="PAYMENT_CARD"></primer-payment-method></div><!-- CORRECT: Use one or the other --><div slot="payments"> <primer-card-form>...</primer-card-form> <primer-payment-method type="PAYPAL"></primer-payment-method></div>
Inputs outside the form context
Card input components must be descendants of <primer-card-form>. They won’t work if placed outside.
When rendering card forms dynamically, ensure the parent <primer-card-form> exists before adding input children:
// WRONG: Adding inputs before the formcontainer.innerHTML = ` <primer-input-card-number></primer-input-card-number> <primer-card-form></primer-card-form>`;// CORRECT: Form first, then inputscontainer.innerHTML = ` <primer-card-form> <div slot="card-form-content"> <primer-input-card-number></primer-input-card-number> </div> </primer-card-form>`;
Missing slot attribute
When customizing the card form layout, always use the card-form-content slot:
<!-- WRONG: Content not in a slot --><primer-card-form> <div> <primer-input-card-number></primer-input-card-number> </div></primer-card-form><!-- CORRECT: Content in the card-form-content slot --><primer-card-form> <div slot="card-form-content"> <primer-input-card-number></primer-input-card-number> </div></primer-card-form>
Forgetting to observe state
Always collect the controller’s state using collectAsStateWithLifecycle(). Without it, your UI won’t update when the user types or when validation changes.
// WRONG: State not observedval formState = controller.state.value// CORRECT: State observed reactivelyval formState by controller.state.collectAsStateWithLifecycle()
Creating the controller outside PrimerCheckoutHost
The card form controller must be created within the PrimerCheckoutHost or PrimerCheckoutSheet scope.
Use the PrimerCardFormSession passed into each slot closure. It is the session for the form you are rendering, and the form keeps passing you the current one when the checkout restarts. checkoutSession.cardForm is nil until the checkout is ready. The SDK replaces its value when the checkout restarts. Fields built from a session you kept elsewhere stay bound to the old session, not to the form on screen.
// WRONG: Building a field from an unrelated session referencePrimerCardForm(cardDetails: { session in VStack { CardFormDefaults.cardNumber(otherSession) // Wrong session }})// CORRECT: Use the session parameter from this slotPrimerCardForm(cardDetails: { session in VStack { CardFormDefaults.cardNumber(session) }})
Not observing state in a custom subview
When you extract a slot into its own View, mark the captured session as @ObservedObject. Without it, your UI won’t update when validation changes.
// WRONG: Session not observed — button never re-evaluatesstruct SubmitButton: View { let session: PrimerCardFormSession var body: some View { Button("Pay") { session.submit() } .disabled(false) // Always enabled }}// CORRECT: Observe the session so state changes re-renderstruct SubmitButton: View { @ObservedObject var session: PrimerCardFormSession var body: some View { Button("Pay") { session.submit() } .disabled(!session.state.isValid || session.state.isLoading) }}
Complete example
Web
Android
iOS
Here’s a complete example combining all the concepts: