PrimerCardFormScope provides complete control over the card payment form — fields, validation, state, and layout.Declaration @MainActor public protocol PrimerCardFormScope : PrimerPaymentMethodScope where State == PrimerCardFormState
Properties State and context Property Type Description stateAsyncStream<PrimerCardFormState>Stream of form state changes presentationContextPresentationContext.direct (cancel button) or .fromPaymentSelection (back button)dismissalMechanism[DismissalMechanism]Supported dismissal methods cardFormUIOptionsPrimerCardFormUIOptions?UI display options selectCountryPrimerSelectCountryScopeCountry picker scope
Field configurations Each field has a corresponding InputFieldConfig? property:
Property Field cardNumberConfigCard number expiryDateConfigExpiration date cvvConfigCVV/CVC cardholderNameConfigCardholder name postalCodeConfigPostal/ZIP code countryConfigCountry cityConfigCity stateConfigState/province addressLine1ConfigAddress line 1 addressLine2ConfigAddress line 2 phoneNumberConfigPhone number firstNameConfigFirst name lastNameConfigLast name emailConfigEmail retailOutletConfigRetail outlet otpCodeConfigOTP code
Layout customization Property Type Description titleString?Form title text screenCardFormScreenComponent?Full screen replacement. Signature: (any PrimerCardFormScope) -> any View cardInputSectionComponent?Card inputs section replacement billingAddressSectionComponent?Billing address section replacement submitButtonComponent?Submit button section replacement cobadgedCardsView(([String], (String) -> Void) -> any View)?Co-badged card network selector errorScreenErrorComponent?Error display replacement submitButtonTextString?Submit button label showSubmitLoadingIndicatorBoolShow loading spinner on submit
Methods Field update methods Method Description updateCardNumber(_ cardNumber: String)Update card number value updateCvv(_ cvv: String)Update CVV value updateExpiryDate(_ expiryDate: String)Update expiry date value updateCardholderName(_ cardholderName: String)Update cardholder name updatePostalCode(_ postalCode: String)Update postal code updateCity(_ city: String)Update city updateState(_ state: String)Update state/province updateAddressLine1(_ addressLine1: String)Update address line 1 updateAddressLine2(_ addressLine2: String)Update address line 2 updatePhoneNumber(_ phoneNumber: String)Update phone number updateFirstName(_ firstName: String)Update first name updateLastName(_ lastName: String)Update last name updateEmail(_ email: String)Update email updateCountryCode(_ countryCode: String)Update country code updateSelectedCardNetwork(_ network: String)Select card network for co-badged cards updateRetailOutlet(_ retailOutlet: String)Update retail outlet updateOtpCode(_ otpCode: String)Update OTP code updateExpiryMonth(_ month: String)Update expiry month updateExpiryYear(_ year: String)Update expiry year
Generic field access Method Description updateField(_ fieldType: PrimerInputElementType, value: String)Update any field by type getFieldValue(_ fieldType: PrimerInputElementType) -> StringGet current field value setFieldError(_ fieldType:message:errorCode:)Set a custom error clearFieldError(_ fieldType:)Clear a custom error getFieldError(_ fieldType:) -> String?Get current error message getFormConfiguration() -> CardFormConfigurationGet field configuration
Validation state Method Description updateValidationState(_ field: WritableKeyPath<FieldValidationStates, Bool>, isValid: Bool)Update validation state for a specific field. Required when using custom field components via InputFieldConfig(component:).
Use KeyPaths to specify which field to update:
// Mark the CVV field as valid scope. updateValidationState (\. cvv , isValid : true ) // Mark the card number field as invalid scope. updateValidationState (\. cardNumber , isValid : false )
When using SDK-provided fields (e.g., PrimerCardNumberField, PrimerCvvField), validation state is managed automatically.
You only need to call this method when replacing a field with a custom component.
Actions Method Description submit()Validate and submit the form onBack()Navigate back cancel()Cancel the card form
ViewBuilder field methods Each method returns an AnyView containing the SDK-managed field:
Method Parameters PrimerCardNumberFieldlabel: String?, styling: PrimerFieldStyling?PrimerExpiryDateFieldlabel: String?, styling: PrimerFieldStyling?PrimerCvvFieldlabel: String?, styling: PrimerFieldStyling?PrimerCardholderNameFieldlabel: String?, styling: PrimerFieldStyling?PrimerCountryFieldlabel: String?, styling: PrimerFieldStyling?PrimerPostalCodeFieldlabel: String?, styling: PrimerFieldStyling?PrimerCityFieldlabel: String?, styling: PrimerFieldStyling?PrimerStateFieldlabel: String?, styling: PrimerFieldStyling?PrimerAddressLine1Fieldlabel: String?, styling: PrimerFieldStyling?PrimerAddressLine2Fieldlabel: String?, styling: PrimerFieldStyling?PrimerFirstNameFieldlabel: String?, styling: PrimerFieldStyling?PrimerLastNameFieldlabel: String?, styling: PrimerFieldStyling?PrimerEmailFieldlabel: String?, styling: PrimerFieldStyling?PrimerPhoneNumberFieldlabel: String?, styling: PrimerFieldStyling?PrimerRetailOutletFieldlabel: String?, styling: PrimerFieldStyling?PrimerOtpCodeFieldlabel: String?, styling: PrimerFieldStyling?DefaultCardFormViewstyling: PrimerFieldStyling?
public struct PrimerCardFormState : Equatable { var configuration: CardFormConfiguration var data: FormData var fieldErrors: [FieldError] var isLoading: Bool var isValid: Bool var selectedCountry: PrimerCountry? var selectedNetwork: PrimerCardNetwork? var availableNetworks: [PrimerCardNetwork] var surchargeAmountRaw: Int ? var surchargeAmount: String ? var displayFields: [PrimerInputElementType] }
Property Type Description isValidBoolAll required fields pass validation isLoadingBoolForm is submitting fieldErrors[FieldError]Current validation errors selectedNetworkPrimerCardNetwork?Detected card network availableNetworks[PrimerCardNetwork]Available networks for co-badged cards displayFields[PrimerInputElementType]Fields to display selectedCountryPrimerCountry?Selected billing country surchargeAmountString?Formatted surcharge amount
See also
Card Form Layout Builder Interactive card form layout builder
Build a custom card form Step-by-step guide
