Dynamic card image

Learn how to configure the dynamic card image component.

Basic usage

With new card

Create the dynamic card image component and link it to your new card component:

import SwiftUI
import PXPCheckoutSDK

let dynamicConfig = DynamicCardImageComponentConfig(
    frontDynamicCardImageBackground: Image("CardFront"),
    backDynamicCardImageBackground: Image("CardBack")
)

let dynamicCardImage = try pxpCheckout.create(
    .dynamicCardImage,
    componentConfig: dynamicConfig
) as! DynamicCardImageComponent

var submitConfig = CardSubmitComponentConfig()
submitConfig.onPreAuthorisation = { _ in
    // Can use await here for async operations
    return TransactionInitiationData()
}
submitConfig.onPostAuthorisation = { _ in }

let newCardConfig = NewCardComponentConfig(
    dynamicCardImageComponent: dynamicCardImage,
    submit: submitConfig
)
let newCard = try pxpCheckout.create(.newCard, componentConfig: newCardConfig) as! NewCardComponent

VStack(alignment: .leading, spacing: 16) {
    dynamicCardImage.buildContent()
    newCard.buildContent()
}

The dynamic card image component automatically updates as the customer types their card details. You need to include both dynamicCardImage.buildContent() and newCard.buildContent() in your view hierarchy.

Standalone (custom layout)

Create your input components first, then link them to the dynamic card image:

let cardNumber = try pxpCheckout.create(.cardNumber, componentConfig: CardNumberComponentConfig(label: "Card number")) as! CardNumberComponent
let expiry = try pxpCheckout.create(.cardExpiryDate, componentConfig: CardExpiryDateComponentConfig(label: "Expiry")) as! CardExpiryDateComponent
let cvc = try pxpCheckout.create(.cardCvc, componentConfig: CardCvcComponentConfig(label: "CVC", isRequired: true)) as! CardCvcComponent
var holderConfig = CardHolderNameComponentConfig(label: "Name on card")
holderConfig.isRequired = false
let holder = try pxpCheckout.create(.cardHolderName, componentConfig: holderConfig) as! CardHolderNameComponent

var dynConfig = DynamicCardImageComponentConfig()
dynConfig.cardNumberComponent = cardNumber
dynConfig.cardExpiryDateComponent = expiry
dynConfig.cardCvcComponent = cvc
dynConfig.cardHolderNameComponent = holder

let dynamicCardImage = try pxpCheckout.create(.dynamicCardImage, componentConfig: dynConfig) as! DynamicCardImageComponent

VStack {
    dynamicCardImage.buildContent()
    cardNumber.buildContent()
    HStack {
        expiry.buildContent()
        cvc.buildContent()
    }
    holder.buildContent()
}

Configuration

You can customise placeholder text, background images, and text styling:

Property	Description
`cardNumberText` String?	The placeholder text for the card number area. Displayed on the card image when no number is entered. Defaults to SDK localisation.
`cardExpiryDateText` String?	The placeholder text for the expiry date. Displayed on the card image when no expiry is entered. Defaults to SDK localisation.
`cardHolderNameText` String?	The placeholder text for the cardholder name. Displayed on the card image when no name is entered. Defaults to SDK localisation.
`cvcText` String?	The placeholder text for the CVC on the card back. Displayed when no CVC is entered. Defaults to SDK localisation.
`frontDynamicCardImageBackground` Image?	The custom image for the card front. When set, replaces the default gradient background. Defaults to built-in gradient.
`backDynamicCardImageBackground` Image?	The custom image for the card back. When set, replaces the default gradient background. Defaults to built-in gradient.
`textStyling` DynamicCardTextStyling?	The base text styling applied to all fields on the card image. Properties: `color`, `fontSize`, `fontWeight`, `opacity`, `textCase`. Defaults to `nil`.
`cvcLabelTextStyling` DynamicCardTextStyling?	The CVC label styling (e.g., "CVV"). Overrides `textStyling` for this element. Defaults to `nil`.
`cvcValueTextStyling` DynamicCardTextStyling?	The CVC value styling. Overrides `textStyling` for this element. Defaults to `nil`.
`bankNameTextStyling` DynamicCardTextStyling?	The bank name styling. Overrides `textStyling` for this element. Defaults to `nil`.
`cardNumberTextStyling` DynamicCardTextStyling?	The card number styling. Overrides `textStyling` for this element. Defaults to `nil`.
`expiryDateLabelTextStyling` DynamicCardTextStyling?	The expiry date label styling (e.g., "Valid Thru"). Overrides `textStyling` for this element. Defaults to `nil`.
`expiryDateValueTextStyling` DynamicCardTextStyling?	The expiry date value styling. Overrides `textStyling` for this element. Defaults to `nil`.
`holderNameTextStyling` DynamicCardTextStyling?	The cardholder name styling. Overrides `textStyling` for this element. Defaults to `nil`.
`highlightFieldStyling` DynamicCardHighlightStyling?	The field focus highlight styling. Applied when a field is focused. Properties: `color`, `backgroundColor`, `borderColor`, `borderWidth`, `backgroundOpacity`. Defaults to `nil`.
`cardNumberComponent` CardNumberComponent?	The linked card number component. When set, the dynamic card image updates as the user types. Defaults to `nil`.
`cardExpiryDateComponent` CardExpiryDateComponent?	The linked expiry date component. When set, the dynamic card image displays the expiry date. Defaults to `nil`.
`cardCvcComponent` CardCvcComponent?	The linked CVC component. When set, the card flips to show the back when focused. Defaults to `nil`.
`cardHolderNameComponent` CardHolderNameComponent?	The linked cardholder name component. When set, the dynamic card image displays the name. Defaults to `nil`.

Text styling

You can customise how text appears on the card image:

`DynamicCardTextStyling`

Property	Description
`color` Color?	The text colour. Defaults to `nil`.
`fontSize` CGFloat	The text size in points. Defaults to 16.
`fontWeight` Font.Weight	The text weight. Options include `.regular`, `.medium`, `.semibold`, `.bold`. Defaults to `.regular`.
`opacity` Double?	The text opacity (0.0 to 1.0). Defaults to `nil`.
`textCase` Text.Case?	The text case transformation. Options include `.uppercase`, `.lowercase`. Defaults to `nil`.

`DynamicCardHighlightStyling`

Property	Description
`color` Color?	The highlight text colour. Applied to focused fields. Defaults to `nil`.
`backgroundColor` Color?	The highlight background colour. Applied behind focused fields. Defaults to `nil`.
`borderColor` Color?	The highlight border colour. Surrounds focused fields. Defaults to `nil`.
`borderWidth` CGFloat?	The highlight border width in points. Defaults to `nil`.
`backgroundOpacity` Double?	The highlight background opacity (0.0 to 1.0). Defaults to `nil`.

Methods

`buildContent()`

Returns SwiftUI content for the dynamic card image:

dynamicCardImage.buildContent()

Examples

Basic card preview

Display a simple card preview with default styling:

let dynamicConfig = DynamicCardImageComponentConfig()
let dynamicCardImage = try pxpCheckout.create(.dynamicCardImage, componentConfig: dynamicConfig) as! DynamicCardImageComponent

var submitConfig = CardSubmitComponentConfig()
submitConfig.onPreAuthorisation = { _ in
    // Can use await here for async operations
    return TransactionInitiationData()
}
submitConfig.onPostAuthorisation = { _ in }

let newCardConfig = NewCardComponentConfig(
    dynamicCardImageComponent: dynamicCardImage,
    submit: submitConfig
)
let newCard = try pxpCheckout.create(.newCard, componentConfig: newCardConfig) as! NewCardComponent

VStack(alignment: .leading, spacing: 16) {
    dynamicCardImage.buildContent()
    newCard.buildContent()
}

Custom card styling

Apply custom styling to the card text:

var dynamicConfig = DynamicCardImageComponentConfig()
dynamicConfig.textStyling = DynamicCardTextStyling(
    color: .white,
    fontSize: 18,
    fontWeight: .medium
)
dynamicConfig.cardNumberTextStyling = DynamicCardTextStyling(
    fontSize: 20,
    fontWeight: .semibold,
    textCase: .uppercase
)
dynamicConfig.highlightFieldStyling = DynamicCardHighlightStyling(
    color: .yellow,
    backgroundColor: .blue.opacity(0.2),
    borderColor: .blue,
    borderWidth: 2
)

let dynamicCardImage = try pxpCheckout.create(.dynamicCardImage, componentConfig: dynamicConfig) as! DynamicCardImageComponent

Custom card images

Use your own card background images:

var dynamicConfig = DynamicCardImageComponentConfig(
    frontDynamicCardImageBackground: Image("CustomCardFront"),
    backDynamicCardImageBackground: Image("CustomCardBack")
)
dynamicConfig.cardNumberText = "Card Number"
dynamicConfig.cardExpiryDateText = "Valid Thru"
dynamicConfig.cardHolderNameText = "Cardholder"
dynamicConfig.cvcText = "CVV"

let dynamicCardImage = try pxpCheckout.create(.dynamicCardImage, componentConfig: dynamicConfig) as! DynamicCardImageComponent

The dynamic card image automatically flips to show the back when the CVC field is focused. For more information about related components, see New card, Card number, and Card CVC.