Card number

Learn how to configure the card number component.

Basic usage

Minimal configuration

The card number component collects the card number with automatic brand detection. At minimum, you can create it with a label:

import SwiftUI
import PXPCheckoutSDK

let cvc = try pxpCheckout.create(
    .cardCvc,
    componentConfig: CardCvcComponentConfig(label: "CVC", isRequired: true)
) as! CardCvcComponent

var config = CardNumberComponentConfig(
    label: "Card number",
    placeholder: "1234 5678 9012 3456",
    acceptedCardBrands: [.visa, .mastercard, .amex, .discover]
)
config.cardCvcComponent = cvc

let cardNumber = try pxpCheckout.create(.cardNumber, componentConfig: config) as! CardNumberComponent

cardNumber.buildContent()

Link the CVC component to the card number so the SDK can automatically adjust CVC validation length for the detected card brand.

Card brand selector

Attach a card brand selector to display card logos:

let brandSelector = try pxpCheckout.create(.cardBrandSelector, componentConfig: CardBrandSelectorComponentConfig()) as! CardBrandSelectorComponent

var cfg = CardNumberComponentConfig(
    label: "Card number",
    acceptedCardBrands: [.visa, .mastercard, .amex]
)
cfg.cardBrandSelectorComponent = brandSelector
cfg.cardCvcComponent = cvc

let cardNumber = try pxpCheckout.create(.cardNumber, componentConfig: cfg) as! CardNumberComponent

Advanced configuration

You can customise formatting, brand detection, validation messages, and event handlers:

let cvc = try pxpCheckout.create(.cardCvc, componentConfig: CardCvcComponentConfig(label: "CVC", isRequired: true)) as! CardCvcComponent
let brandSelector = try pxpCheckout.create(.cardBrandSelector, componentConfig: CardBrandSelectorComponentConfig()) as! CardBrandSelectorComponent

var config = CardNumberComponentConfig(
    label: "Card number",
    placeholder: "1234 5678 9012 3456",
    guideText: "Enter the number from the front of your card",
    formatCardNumber: true,
    renderCardBrandSelector: true,
    acceptedCardBrands: [.visa, .mastercard],
    validations: CardNumberValidationResource(
        CN01: "Card number is required",
        CN02: "Digits only",
        CN03: "Number is too short",
        CN04: "Card type not recognised",
        CN05: "This card type is not accepted",
        CN06: "Check the card number",
        CN07: "%@ not accepted",
        CN08: "Card type is not detected"
    ),
    cardBrandSelectorSpacing: 12,
    showHintIcon: true,
    showTooltip: true,
    validationOnBlur: true,
    validationOnChange: true,
    onCardBrandDetected: { event in
        print("Brand detected:", event.cardBrand)
        print("Is accepted:", event.isCardBrandAccepted)
    },
    onCardBrandCannotRecognised: { event in
        print("Brand not recognised")
    }
)

config.cardCvcComponent = cvc
config.cardBrandSelectorComponent = brandSelector
config.componentStyles = FieldStyle(cornerRadius: 8)
config.displayValidIcon = true

let cardNumber = try pxpCheckout.create(.cardNumber, componentConfig: config) as! CardNumberComponent

Property	Description
`formatCardNumber` Bool	Whether to insert spaces while typing. When `true`, the SDK automatically formats the card number with spaces for readability. Defaults to `true`.
`renderCardBrandSelector` Bool?	Whether to show the linked brand selector. When `true` and a brand selector component is linked, the selector is displayed alongside the card number field. Defaults to `true` when a selector is linked.
`acceptedCardBrands` [CardBrandType]?	The list of accepted card brands (e.g. `.visa`, `.mastercard`, `.amex`, `.discover`, `.jcb`, `.diners`, `.cup`). When specified, the SDK validates that the detected brand is in this list. Defaults to `nil`.
`validations` CardNumberValidationResource?	Custom validation messages for CN01-CN08 error codes. Overrides SDK default messages. Defaults to `nil`.
`cardCvcComponent` CardCvcComponent?	The linked CVC component for brand-specific length validation. When linked, the SDK automatically adjusts CVC validation length based on the detected card brand (3 digits for most cards, 4 for Amex). Defaults to `nil`.
`cardBrandSelectorComponent` CardBrandSelectorComponent?	The linked brand selector for displaying card logos. Automatically updates to show detected card brands. Defaults to `nil`.
`cardBrandSelectorSpacing` CGFloat?	The spacing between the number field and selector in points. Defaults to `8`.
`onCardBrandDetected` ((CardBrandDetectionEvent) -> Void)?	Event handler called when a card brand is detected. Receives event with `cardBrand` and `isCardBrandAccepted` properties. Defaults to `nil`.
`onCardBrandCannotRecognised` ((CardBrandDetectionEvent) -> Void)?	Event handler called when card brand can't be recognised. Triggered when the entered number doesn't match any known card brand patterns. Defaults to `nil`.
`shouldEncrypt` Bool	Whether to encrypt the value when read. For the card number component, this is always `true` and can't be changed. The card number is always encrypted before transmission for security.
`showHintIcon` Bool	Whether to show a hint icon beside the field. Helps users locate the card number on their card. 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. For the card number component, this is always `true` and can't be changed. The card number field must have a value before the payment can be submitted.
`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 card number component provides event handlers for user interaction, validation, and brand detection:

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.
`onCardBrandDetected: ((CardBrandDetectionEvent) -> Void)?`	Called when a known card brand is detected. Receives event with `cardBrand` and `isCardBrandAccepted` properties.
`onCardBrandCannotRecognised: ((CardBrandDetectionEvent) -> Void)?`	Called when the card brand can't be recognised from the entered number.
`onPaste: (() -> Void)?`	Called when user pastes into the field.

For more information about event patterns, see Events.

Validation

The card number component validates user input against the following rules:

Code	Condition	Default message
CN01	Required but empty	"Please enter card number"
CN02	Non-numeric characters	"Invalid card number. Please enter a numeric value"
CN03	Number too short for detected brand	"Your card number is incomplete"
CN04	Card brand not recognised	"Please enter a valid card number"
CN05	Card brand not in accepted list	"Card network is not supported"
CN06	Card number failed Luhn validation	"Please enter a valid card number"
CN07	Custom validation with format argument	"%@ not accepted" (dynamic - brand name inserted)
CN08	Card type not detected	"Card type is not detected"

Validation triggers based on your configuration (validationOnBlur, validationOnChange). Override default messages using the validations property. When linked to a CVC component, the SDK automatically adjusts CVC validation for the detected brand.

Methods

`buildContent()`

Returns SwiftUI content for the card number field:

cardNumber.buildContent()

Examples

Disable formatting

Display the card number without spacing:

let cvc = try pxpCheckout.create(.cardCvc, componentConfig: CardCvcComponentConfig(label: "CVC", isRequired: true)) as! CardCvcComponent
var cfg = CardNumberComponentConfig(label: "Card number", formatCardNumber: false)
cfg.cardCvcComponent = cvc
let cardNumber = try pxpCheckout.create(.cardNumber, componentConfig: cfg) as! CardNumberComponent

Hide brand selector UI

Link a brand selector but hide its display:

let brandSelector = try pxpCheckout.create(.cardBrandSelector, componentConfig: CardBrandSelectorComponentConfig()) as! CardBrandSelectorComponent
var cfg = CardNumberComponentConfig(label: "Card number", renderCardBrandSelector: false)
cfg.cardBrandSelectorComponent = brandSelector
cfg.acceptedCardBrands = [.visa, .mastercard]
let cardNumber = try pxpCheckout.create(.cardNumber, componentConfig: cfg) as! CardNumberComponent

Wire the card number component into Card submit or New card. For brand logos and display modes, see Card brand selector.