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
)

Card restrictions

You can restrict what card types the new card component accepts by configuring the restrictions parameter in PxpSdkConfig. This provides frontend validation based on card owner type and funding source.

val sdkConfig = PxpSdkConfig(
    // ... other config
    restrictions = Restrictions(
        card = RestrictionsCard(
            ownerTypes = listOf(RestrictionOwnerType.CONSUMER),
            fundingSources = listOf(RestrictionFundingSource.CREDIT, RestrictionFundingSource.DEBIT)
        )
    )
)

Restriction	Description
`ownerTypes`	Restricts cards based on the card owner segment. Possible values: `RestrictionOwnerType.CORPORATE` `RestrictionOwnerType.CONSUMER`
`fundingSources`	Restricts cards based on the funding source. Possible values: `RestrictionFundingSource.PREPAID` `RestrictionFundingSource.CREDIT` `RestrictionFundingSource.DEBIT`

Card restrictions work alongside component-level acceptedCardBrands validation. Both validations must pass for a card to be accepted. See Data validation for details.