New card

Learn customisation options for the new card component.

Styling

val newCardComponentConfig = NewCardComponentConfig(
    fields = Fields,
    newCardStyle = NewCardStyle,
    dynamicCardImageComponent = DynamicCardImageComponent?,
    displayRequiredIcon = Boolean?,
    autoFlipCardOnCvcFocus = Boolean,
    submit = CardSubmitComponentConfig?
)

Property	Description
`fields` Fields	Configuration for card form fields. Contains nested configurations for individual card components.
`newCardStyle` NewCardStyle	New card component specific styling configuration. Defaults to default style.
`dynamicCardImageComponent` DynamicCardImageComponent?	Optional reference to a dynamic card image component for visual card representation. See Dynamic card image.
`displayRequiredIcon` Boolean?	Whether to show a required icon for all required fields.
`autoFlipCardOnCvcFocus` Boolean	Whether to automatically flip the card when the CVC field is focused. Only applies when `dynamicCardImageComponent` is set. Defaults to `true`.
`submit` CardSubmitComponentConfig?	Configuration for the submit button, including custom validation support via `onCustomValidation`. See Card submit.

Fields configuration

The fields property contains nested configurations for individual card components:

class Fields {
    var cardNumber: CardNumberComponentConfig? = null
    var expiryDate: CardExpiryDateComponentConfig? = null
    var cvc: CardCvcComponentConfig? = null
    var holderName: CardHolderNameComponentConfig? = null
    var cardBrandSelector: CardBrandSelectorConfig? = null
    var cardConsent: CardConsentConfig? = null
}

Field	Description
`cardNumber` CardNumberComponentConfig?	Card number field configuration. If null, uses default configuration.
`expiryDate` CardExpiryDateComponentConfig?	Card expiry date field configuration. If null, uses default configuration.
`cvc` CardCvcComponentConfig?	Card CVC/CVV field configuration. If null, uses default configuration.
`holderName` CardHolderNameComponentConfig?	Card holder name field configuration. If null, uses default configuration.
`cardBrandSelector` CardBrandSelectorConfig?	Card brand selector configuration. If null, uses default configuration.
`cardConsent` CardConsentConfig?	Card consent field configuration. If null, consent field is not shown.

Callbacks

data class NewCardComponentConfig(
    val onValidationPassed: ((List<ValidationResult>) -> Unit)? = null,
    val onValidationFailed: ((List<ValidationResult>) -> Unit)? = null,
    val onTriggerFieldValidation: ((ValidationResult) -> Unit)? = null
)

Callback	Description
`onValidationPassed: ((List<ValidationResult>) -> Unit)?`	Event handler for when validation passes. Inherited from ComponentConfigImpl.
`onValidationFailed: ((List<ValidationResult>) -> Unit)?`	Event handler for when validation fails. Inherited from ComponentConfigImpl.
`onTriggerFieldValidation: ((ValidationResult) -> Unit)?`	Event handler for when field validation is triggered individually. Inherited from ComponentConfigImpl.

For more information about callbacks, see Events.

Example

import com.pxp.checkout.components.newCard.NewCardComponent
import com.pxp.checkout.components.newCard.NewCardComponentConfig
import com.pxp.checkout.components.cardnumber.CardNumberComponentConfig
import com.pxp.checkout.components.cardexpirydate.CardExpiryDateComponentConfig
import com.pxp.checkout.components.cardcvc.CardCvcComponentConfig
import com.pxp.checkout.components.cardholdername.CardHolderNameComponentConfig
import com.pxp.checkout.components.cardbrandselector.CardBrandSelectorConfig
import com.pxp.checkout.components.cardconsent.CardConsentConfig
import com.pxp.checkout.components.cardsubmit.CardSubmitComponentConfig
import com.pxp.checkout.components.dynamicCardImage.DynamicCardImageComponent
import com.pxp.checkout.styles.NewCardStyle

// Create dynamic card image component (optional)
val dynamicCardImageComponent = checkout.createComponent<DynamicCardImageComponent, DynamicCardImageComponentConfig>(
    type = ComponentType.DYNAMIC_CARD_IMAGE,
    config = DynamicCardImageComponentConfig(
        cardDisplayMode = CardDisplayMode.BOTH_STAGGERED,
        highlightedCardField = CardFieldType.CARD_NUMBER
    )
)

// Configure individual fields
val fields = NewCardComponentConfig.Fields().apply {
    // Card number configuration
    cardNumber = CardNumberComponentConfig(
        label = "Card Number",
        placeholder = "1234 5678 9012 3456",
        formatCardNumber = true,
        acceptedCardBrands = listOf(CardBrand.VISA, CardBrand.MASTERCARD, CardBrand.AMEX),
        onCardBrandChanged = { brand ->
            println("Card brand detected: $brand")
        }
    )
    
    // Expiry date configuration
    expiryDate = CardExpiryDateComponentConfig(
        label = "Expiry Date",
        placeholder = "MM/YY",
        formatOptions = ExpiryDateFormat.MM_YY,
        dynamicCardImageComponent = dynamicCardImageComponent
    )
    
    // CVC configuration
    cvc = CardCvcComponentConfig(
        label = "CVC",
        placeholder = "123",
        showMaskToggle = true,
        applyMask = false,
        dynamicCardImageComponent = dynamicCardImageComponent
    )
    
    // Cardholder name configuration
    holderName = CardHolderNameComponentConfig(
        label = "Cardholder Name",
        placeholder = "John Doe",
        autoCapitalise = true,
        maxLength = 100,
        dynamicCardImageComponent = dynamicCardImageComponent
    )
    
    // Card brand selector configuration (optional)
    cardBrandSelector = CardBrandSelectorConfig(
        allowedBrands = listOf(CardBrand.VISA, CardBrand.MASTERCARD, CardBrand.AMEX),
        onBrandChange = { brand ->
            println("Manual brand selection: $brand")
        }
    )
    
    // Card consent configuration (optional)
    cardConsent = CardConsentConfig(
        label = "Save this card for future payments",
        initialChecked = false
    )
}

// Configure submit button (optional)
val submitConfig = CardSubmitComponentConfig(
    buttonText = "Add Card",
    loadingText = "Adding Card...",
    disableUntilValidated = true,
    onSubmit = {
        println("New card form submitted")
    }
)

// Optional: Create custom styling
val customStyle = NewCardStyle(
    fieldSpacing = 16.dp,
    borderRadius = 8.dp,
    backgroundColor = Color.White,
    borderColor = Color.Gray
)

val config = NewCardComponentConfig(
    // Field configurations
    fields = fields,
    
    // Dynamic card image integration
    dynamicCardImageComponent = dynamicCardImageComponent,
    autoFlipCardOnCvcFocus = true,
    
    // Submit button integration
    submit = submitConfig,
    
    // Display configuration
    displayRequiredIcon = true,
    
    // Styling
    newCardStyle = customStyle
)

val newCardComponent = checkout.createComponent<NewCardComponent, NewCardComponentConfig>(
    type = ComponentType.NEW_CARD,
    config = config
)

New card

Styling

Fields configuration

Callbacks

Example

Was this helpful?