Card expiry date

Learn how to configure the card expiry date component.

Basic usage

Minimal configuration

The card expiry date component collects the card's expiration date. At minimum, you can create it with a label:

import SwiftUI
import PXPCheckoutSDK

let config = CardExpiryDateComponentConfig(
    label: "Expiry date",
    placeholder: "MM/YY"
)

let expiry = try pxpCheckout.create(.cardExpiryDate, componentConfig: config) as! CardExpiryDateComponent

expiry.buildContent()

Advanced configuration

You can customise the format, validation messages, hint icons, and styling:

var config = CardExpiryDateComponentConfig(
    label: "Expiry",
    placeholder: "MM/YY",
    guideText: "Use the date printed on your card",
    defaultValue: nil,
    numberOfMonthExpired: 0,
    formatOptions: .mmYY,
    validations: CardExpiryDateValidationResource(
        ED01: "Expiry date is required",
        ED02: "Month must be between 01 and 12",
        ED03: "Year is not valid",
        ED04: "Card has expired",
        ED05: "Use the format MM/YY"
    ),
    showHintIcon: true,
    showTooltip: false,
    validationOnBlur: true,
    validationOnChange: false
)

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

let expiry = try pxpCheckout.create(.cardExpiryDate, componentConfig: config) as! CardExpiryDateComponent

Property	Description
`defaultValue` String?	The pre-filled display value. When set, the field initially shows this expiry date. Defaults to `nil`.
`numberOfMonthExpired` Int?	The additional months after printed expiry before treating the card as expired. Extends the validation grace period beyond the printed date. Defaults to `nil`.
`formatOptions` CardExpiryDateFormatOption?	The display and validation format. Options: `.mmYY` (12/25), `.mmYYYY` (12/2025), `.mmDashYY` (12-25), `.mmDotYY` (12.25). Defaults to `nil`.
`validations` CardExpiryDateValidationResource?	Custom validation messages for ED01-ED05 error codes. Overrides SDK default messages. Defaults to `nil`.
`shouldEncrypt` Bool	Whether to encrypt the value when read. When `true`, the expiry date is encrypted before transmission. Defaults to `false`.
`showHintIcon` Bool	Whether to show a hint icon beside the field. Helps users locate the expiry date 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 expiry date component, this is always `true` and can't be changed. The expiry date field is always required for payment processing.
`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`.

Format options

`CardExpiryDateFormatOption`	Example	Separator	Max length
`.mmYY`	`12/25`	`/`	5
`.mmYYYY`	`12/2025`	`/`	7
`.mmDashYY`	`12-25`	`-`	5
`.mmDotYY`	`12.25`	`.`	5

Event handling

The card expiry date 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 expiry date component validates user input against the following rules:

Code	Condition	Default message
`ED01`	Contains non-numeric characters	"Expiry date must contain only digits"
`ED02`	Invalid month (not between 01-12)	"Invalid month. Please enter a month between 01 and 12"
`ED03`	Format doesn't match selected pattern	"Invalid expiry date format. Please use"
`ED04`	Card has expired	"The card expiry date you entered has already passed. Please enter a valid expiration date"
`ED05`	Empty value	"Please enter expiry date"

Validation triggers based on your configuration (validationOnBlur, validationOnChange). Override default messages using the validations property. Use numberOfMonthExpired to extend the grace period beyond the printed expiry date.

Methods

`buildContent()`

Returns SwiftUI content for the expiry date field:

expiry.buildContent()

Examples

Four-digit year

Use a four-digit year format:

let config = CardExpiryDateComponentConfig(
    label: "Expiry",
    placeholder: "MM/YYYY",
    formatOptions: .mmYYYY
)
let expiry = try pxpCheckout.create(.cardExpiryDate, componentConfig: config) as! CardExpiryDateComponent

Custom styling

Configure custom input and border styling:

var cfg = CardExpiryDateComponentConfig(label: "Expires", formatOptions: .mmYY)
cfg.inputStyles = FieldInputStateStyles(
    base: FieldInputStyle(cornerRadius: 8, borderWidth: 1, borderColor: Color(.separator)),
    invalid: FieldInputStyle(borderColor: .red)
)
let expiry = try pxpCheckout.create(.cardExpiryDate, componentConfig: cfg) as! CardExpiryDateComponent

Pass cardExpiryDateComponent into Card submit, or use New card, to include expiry in payment flows. See Data validation.