Cardholder name

Learn how to configure the cardholder name component.

Basic usage

Minimal configuration

The cardholder name component collects the name on the card. At minimum, you can create it with a label:

import SwiftUI
import PXPCheckoutSDK

var config = CardHolderNameComponentConfig(
    label: "Name on card",
    placeholder: "J SMITH"
)
config.isRequired = true

let holderName = try pxpCheckout.create(.cardHolderName, componentConfig: config) as! CardHolderNameComponent

holderName.buildContent()

Advanced configuration

You can customise auto-capitalization, validation messages, hint icons, and styling:

var config = CardHolderNameComponentConfig(
    label: "Cardholder name",
    placeholder: "As shown on card",
    guideText: "Use the name printed on your card",
    autoCapitalise: true,
    defaultValue: nil,
    validations: CardHolderNameValidationResource(
        HN01: "Enter the cardholder name",
        HN02: "Name is too short",
        HN03: "Use letters, spaces, or hyphens only",
        HN04: "Name is too long"
    ),
    showHintIcon: true,
    showTooltip: true,
    validationOnBlur: true,
    validationOnChange: false
)

config.isRequired = true
config.componentStyles = FieldStyle(cornerRadius: 8)
config.displayValidIcon = true

let holderName = try pxpCheckout.create(.cardHolderName, componentConfig: config) as! CardHolderNameComponent

Property	Description
`autoCapitalise` Bool	Whether to automatically capitalise the first letter of each word (title case). When `true`, text is converted to title case as the user types (for example "john smith" becomes "John Smith"). Defaults to `true`.
`defaultValue` String?	The pre-filled display value. When set, the field initially shows this cardholder name. Defaults to `nil`.
`validations` CardHolderNameValidationResource?	Custom validation messages for HN01-HN04 error codes. Overrides SDK default messages. Defaults to `nil`.
`shouldEncrypt` Bool	Whether to encrypt the value when read. When `true`, the cardholder name is encrypted before transmission. Defaults to `false`.
`showHintIcon` Bool	Whether to show a hint icon beside the field. Helps users understand what name to enter. Defaults to `false`.
`showTooltip` Bool	Whether to show tooltip behaviour with the hint. When `true`, displays additional information when the hint icon is tapped. Defaults to `false`.
`hintIcon` Image?	The custom hint icon image. Defaults to `nil`.
`tooltipIcon` Image?	The custom tooltip trigger image. Defaults to `nil`.
`maskHiddenIcon` Image?	The icon when value is masked. Defaults to `nil`.
`maskVisibleIcon` Image?	The icon when value is visible. Defaults to `nil`.
`onPaste` (() -> Void)?	Event handler called when user pastes into the field. Defaults to `nil`.
`label` String?	The field label text. Defaults to `nil`.
`placeholder` String?	The placeholder text shown when the field is empty. Defaults to `nil`.
`guideText` String?	The helper text displayed below the field. Defaults to `nil`.
`accessibilityLabel` String?	The accessibility label for the input. Defaults to `nil`.
`isRequired` Bool	Whether the field is required. When `true`, the field must have a value before the payment can be submitted. Defaults to `false`.
`componentStyles` FieldStyle?	The container styling. Defaults to `nil`. Properties: `color`, `font`, `fontWeight`, `fontSize`, `labelFont`, `labelColor`, `valueFont`, `valueColor`, `backgroundColor`, `borderColor`, `borderWidth`, `cornerRadius`, `padding`, `margin`, `textAlignment`, `opacity`, `shadow` (ShadowStyle), `icon` (IconStyle), `labelSpacing`.
`inputStyles` FieldInputStateStyles?	The input styling for different states. Defaults to `nil`. States: `base` (default unfocused), `active` (focused), `valid` (has valid value), `invalid` (has invalid value). Each state supports: `color`, `placeholderColor`, `fontWeight`, `fontSize`, `backgroundColor`, `borderColor`, `borderWidth`, `cornerRadius`, `padding`, `minHeight`.
`labelStyles` FieldLabelStateStyles?	The label styling by state. Defaults to `nil`. States: `base` (default), `active` (focused), `valid` (has valid value), `invalid` (has invalid value). Each state supports: `color`, `font`. Additional property: `minWidth` (CGFloat? - default: 80).
`labelPosition` LabelPosition?	The label position relative to input. Options: `above`, `below`, `left`, `right`. Defaults to `nil`.
`invalidTextStyle` FieldMessageStyle?	The error message styling. Defaults to `nil`. Properties: `color`, `font`.
`invalidTextPosition` TextPosition?	The error message placement. Defaults to `nil`.
`guideTextStyle` FieldMessageStyle?	The guide text styling. Defaults to `nil`. Properties: `color`, `font`.
`invalidIcon` Image?	The custom invalid state icon. Defaults to `nil`.
`validIcon` Image?	The custom valid state icon. Defaults to `nil`.
`displayValidIcon` Bool	Whether to show the valid icon. Defaults to `false`.
`displayInvalidIcon` Bool	Whether to show the invalid icon. Defaults to `true`.
`tooltipAccessibilityLabel` String?	The tooltip accessibility label. Defaults to `nil`.
`displayRequiredIcon` Bool?	Whether to display the required indicator. Defaults to `nil`.
`allowToCopyPaste` Bool	Whether to allow copy and paste. Defaults to `true`.
`validationOnBlur` Bool	Whether to validate when the field loses focus. Defaults to `true`.
`validationOnChange` Bool	Whether to validate on each change. Defaults to `false`.
`isDisabled` Bool	Whether the field is disabled. Defaults to `false`.

Event handling

The cardholder name component provides event handlers for user interaction and validation:

Callback	Description
`onChange: (() -> Void)?`	Called when the field value changes.
`onFocus: (() -> Void)?`	Called when the field gains focus.
`onBlur: (() -> Void)?`	Called when the field loses focus.
`onValidationPassed: (([ValidationResult]) -> Void)?`	Called when all validation checks pass. Receives an array of validation results.
`onValidationFailed: (([ValidationResult]) -> Void)?`	Called when validation fails. Receives an array of validation results containing error details.
`onPaste: (() -> Void)?`	Called when user pastes into the field.

For more information about event patterns, see Events.

Validation

The cardholder name component validates user input against the following rules:

Code	Condition	Default message
HN01	Required but empty	"Please enter card holder name"
HN02	Fewer than 3 characters	"Card holder name minimum length is 3"
HN03	Contains invalid characters	"The card holder name must be string containing only alphabetic characters, spaces and hyphens"
HN04	More than 100 characters	"Card holder name maximum length is 100"

Validation triggers based on your configuration (validationOnBlur, validationOnChange). Override default messages using the validations property. Only letters, spaces, and hyphens are allowed.

Methods

`buildContent()`

Returns SwiftUI content for the cardholder name field:

holderName.buildContent()

Examples

Prefill and disable auto-capitalisation

Prefill the name and disable automatic title case conversion:

var config = CardHolderNameComponentConfig(
    label: "Name on card",
    defaultValue: "Jane Doe",
    autoCapitalise: false
)
config.isRequired = true
let holderName = try pxpCheckout.create(.cardHolderName, componentConfig: config) as! CardHolderNameComponent

Optional name

Create an optional cardholder name field:

let config = CardHolderNameComponentConfig(label: "Name (optional)")
let holderName = try pxpCheckout.create(.cardHolderName, componentConfig: config) as! CardHolderNameComponent

Pass the component into Card submit or New card. For validation details, see Data validation.