Validation - Primer

Primer Checkout iOS SDK is currently in beta (v3.0.0-beta.8). The API is subject to change before the stable release.

The card form’s built-in field views validate each field and surface the results through PrimerCardFormState. A field shows an error when the shopper leaves it with an invalid value. The CVV field also validates as soon as it reaches its full length. The error clears when the shopper focuses that field again. Empty fields never show an error message. Values you write with the session’s update* methods never produce a FieldError. They count toward isValid only while the matching SDK field view is on screen. Read validation state from the PrimerCardFormSession inside your custom slots to display targeted messages and gate submission.

FieldError

A FieldError represents a validation error for a single form field. It is Equatable and Identifiable (its id is the fieldType), so it works directly with SwiftUI’s ForEach.

@available(iOS 15.0, *)
public struct FieldError: Equatable, Identifiable {
    public var id: PrimerInputElementType { fieldType }
    public let fieldType: PrimerInputElementType
    public let message: String
    public let errorCode: String?

    public init(
        fieldType: PrimerInputElementType,
        message: String,
        errorCode: String? = nil
    )
}

Property	Type	Description
`id`	`PrimerInputElementType`	Deterministic identifier based on `fieldType` for stable SwiftUI diffing.
`fieldType`	`PrimerInputElementType`	The type of field that has the error.
`message`	`String`	Human-readable error message to display to the user.
`errorCode`	`String?`	Machine-readable error code for programmatic handling.

Validation surfaces on PrimerCardFormState

Validation is exposed through the form state held by PrimerCardFormSession. Observe the session your slot receives with @ObservedObject and read session.state.

Member	Type	Description
`fieldErrors`	`[FieldError]`	Field-specific validation errors currently present in the form.
`isValid`	`Bool`	`true` when the card number, expiry date, CVV and cardholder name fields are all valid. Billing address fields don’t affect it. Use this to enable or disable your submit button.
`hasError(for:)`	`(PrimerInputElementType) -> Bool`	Returns `true` when the given field currently has an error.
`errorMessage(for:)`	`(PrimerInputElementType) -> String?`	Returns the first error message for the given field, or `nil` if the field has no error.

@available(iOS 15.0, *)
public struct PrimerCardFormState: Equatable {
    public internal(set) var fieldErrors: [FieldError]
    public internal(set) var isValid: Bool

    public func hasError(for fieldType: PrimerInputElementType) -> Bool
    public func errorMessage(for fieldType: PrimerInputElementType) -> String?
}

isValid is true while the SDK’s card number, expiry date, CVV and cardholder name fields all hold valid values. Billing address fields don’t count toward it. While isValid is true, the SDK keeps fieldErrors empty. It clears every entry whenever a field’s validity updates, billing errors included. Use isValid to drive the enabled state of your submit button, and use fieldErrors / errorMessage(for:) to render per-field messages.

Reading a field error inside a slot

Validation runs inside the SDK’s own field views (the CardFormDefaults building blocks), which also show the field’s error message. The update* methods on PrimerCardFormSession store a value but never produce a validation error. A TextField of your own never produces a FieldError. Keep the SDK field and use the helpers on session.state to add your own UI around it. The example below adds a hint under the CVV field while it has an error.

import SwiftUI
import PrimerSDK

@available(iOS 15.0, *)
struct CvvField: View {
    @ObservedObject var session: PrimerCardFormSession

    var body: some View {
        VStack(alignment: .leading, spacing: 4) {
            CardFormDefaults.cvv(session)

            if session.state.hasError(for: .cvv) {
                Text("You can find the security code on the back of your card.")
                    .font(.footnote)
                    .foregroundColor(.secondary)
            }
        }
    }
}

To enumerate every error currently present in the form, iterate fieldErrors directly — FieldError is Identifiable, so it slots into ForEach.

ForEach(session.state.fieldErrors) { error in
    Text("\(error.fieldType.stringValue): \(error.message)")
        .font(.footnote)
        .foregroundColor(.red)
}

Gating submission with isValid

Bind your submit button’s enabled state to session.state.isValid so it activates only once the form passes validation.

Button("Pay") {
    session.submit()
}
.disabled(!session.state.isValid)

PrimerInputElementType

PrimerInputElementType identifies the type of input field referenced by a FieldError (and used throughout the card form). Each case has a stringValue returning the canonical string identifier.

@objc
public enum PrimerInputElementType: Int {
    case cardNumber
    case expiryDate
    case cvv
    case cardholderName
    case otp
    case postalCode
    case phoneNumber
    case retailer
    case unknown
    case countryCode
    case firstName
    case lastName
    case addressLine1
    case addressLine2
    case city
    case state
    case email
    case all

    public var stringValue: String { get }
}

Case	`stringValue`	Description
`cardNumber`	`CARD_NUMBER`	Credit/debit card number (e.g., “4242 4242 4242 4242”).
`expiryDate`	`EXPIRY_DATE`	Card expiration date in MM/YY format.
`cvv`	`CVV`	Card verification value (3-4 digit security code).
`cardholderName`	`CARDHOLDER_NAME`	Name as printed on the card.
`otp`	`OTP`	One-time password for verification flows.
`postalCode`	`POSTAL_CODE`	Postal or ZIP code for billing address.
`phoneNumber`	`PHONE_NUMBER`	Phone number for contact or verification.
`retailer`	`RETAILER`	Retail outlet selection for cash payment methods.
`unknown`	`UNKNOWN`	Unknown or unrecognized field type.
`countryCode`	`COUNTRY_CODE`	ISO country code (e.g., “US”, “GB”).
`firstName`	`FIRST_NAME`	First name for billing address.
`lastName`	`LAST_NAME`	Last name for billing address.
`addressLine1`	`ADDRESS_LINE_1`	Primary street address line.
`addressLine2`	`ADDRESS_LINE_2`	Secondary address line (apartment, suite, etc.).
`city`	`CITY`	City name for billing address.
`state`	`STATE`	State or province for billing address.
`email`	`EMAIL`	Email address for receipts and notifications.
`all`	`ALL`	Represents all fields collectively (used for bulk operations).

You typically don’t construct FieldError yourself. The SDK’s field views populate fieldErrors when the shopper leaves a field. Read it through session.state and use hasError(for:) / errorMessage(for:) to drive your UI.

Card form session

The observable session that exposes form state, mutation methods, and submission.

Card field components

Built-in field views you can compose inside the card form slots.

​FieldError

​Validation surfaces on PrimerCardFormState

​Reading a field error inside a slot

​Gating submission with isValid

​PrimerInputElementType

​See also

Card form session

Card field components

FieldError

Validation surfaces on PrimerCardFormState

Reading a field error inside a slot

Gating submission with isValid

PrimerInputElementType

See also