Card CVC

Learn how to configure the card CVC component.

Basic usage

Minimal configuration

The card CVC component collects the card security code. At minimum, you can create it with a label:

import SwiftUI
import PXPCheckoutSDK

let config = CardCvcComponentConfig(
    label: "CVC",
    placeholder: "123",
    isRequired: true
)

let cvc = try pxpCheckout.create(.cardCvc, componentConfig: config) as! CardCvcComponent

cvc.buildContent()

Link the CVC component to the card number component so the SDK can automatically adjust validation for the detected card brand (3 digits for most cards, 4 for Amex).

Advanced configuration

You can customise masking, validation messages, hint icons, and styling:

var config = CardCvcComponentConfig(
    label: "Security code",
    placeholder: "123",
    guideText: "3 digits on the back; 4 on the front for Amex",
    isRequired: true,
    applyMask: true,
    showMaskToggle: true,
    validations: CardCvcValidationResource(
        CVC01: "Enter the security code",
        CVC02: "Digits only",
        CVC03: "Code is too short",
        CVC04: "Code is too long"
    ),
    maskButtonAccessibilityLabel: "Hide security code",
    unmaskButtonAccessibilityLabel: "Show security code",
    showHintIcon: true,
    showTooltip: true,
    validationOnBlur: true,
    validationOnChange: false
)

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

let cvc = try pxpCheckout.create(.cardCvc, componentConfig: config) as! CardCvcComponent

Property	Description
`applyMask` Bool?	Whether to mask digits (display as bullets). When `true`, the security code is visually hidden for privacy. Defaults to `nil`.
`showMaskToggle` Bool?	Whether to show a reveal/hide control. Requires `applyMask` to be `true`. When enabled, users can toggle between masked and visible security codes. Defaults to `nil`.
`validations` CardCvcValidationResource?	Custom validation messages for CVC01-CVC04 error codes. Overrides SDK default messages. Defaults to `nil`.
`maskButtonAccessibilityLabel` String?	The accessibility label for the hide control. Announced by screen readers when the security code is visible and can be hidden. Defaults to `nil`.
`unmaskButtonAccessibilityLabel` String?	The accessibility label for the show control. Announced by screen readers when the security code is masked and can be revealed. Defaults to `nil`.
`shouldEncrypt` Bool	Whether to encrypt the value when read. For the card CVC component, this is always `true` and can't be changed. The CVC value is always encrypted before transmission for security.
`showHintIcon` Bool	Whether to show a hint icon beside the field. Helps users locate the security code 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. 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 control 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 CVC 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 card CVC component validates user input against the following rules:

Code	Condition	Default message
CVC01	Required but empty	"Please enter security code"
CVC02	Non-numeric characters	"Please enter a valid security code"
CVC03	Too few digits	"Your card's security code is incomplete"
CVC04	Too many digits	"Your card's security code exceeds the maximum length"

Validation triggers based on your configuration (validationOnBlur, validationOnChange). Override default messages using the validations property. When linked to a card number component, the SDK automatically adjusts validation for the detected card brand (3 digits for most cards, 4 for Amex).

Methods

`buildContent()`

Returns SwiftUI content for the CVC field:

cvc.buildContent()

Examples

With card number

Link the CVC component to the card number for automatic validation:

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

var cardConfig = CardNumberComponentConfig(label: "Card number", cardCvcComponent: cvc)
let cardNumber = try pxpCheckout.create(.cardNumber, componentConfig: cardConfig) as! CardNumberComponent

With masking

Enable masking with a toggle control:

var cfg = CardCvcComponentConfig(label: "CVV", isRequired: true)
cfg.applyMask = true
cfg.showMaskToggle = true
let cvc = try pxpCheckout.create(.cardCvc, componentConfig: cfg) as! CardCvcComponent

Use Card submit with cardCvcComponent set, or New card, to include CVC in tokenisation. For validation rules across fields, see Data validation.