# Click-once

Learn about customisation options for the click-once component.

## Styling

```kotlin
val clickOnceComponentConfig = ClickOnceComponentConfig(
    headerTitle = String,
    submitText = String?,
    submitProcessingText = String?,
    selectCardText = String,
    expiredText = String?,
    validThruText = String?,
    hideCardBrandLogo = Boolean,
    disableCardSelection = Boolean,
    isRenderLastPurchaseCard = Boolean,
    isRenderLastPayoutCard = Boolean,
    isCvcRequired = Boolean,
    useTransparentCardBrandImage = Boolean,
    isProcessNextStepOnCardClick = Boolean,
    cvcComponentConfig = CardCvcComponentConfig?,
    cardSubmitComponentConfig = CardSubmitComponentConfig?,
    notificationConfig = NotificationConfig,
    cardBrandImages = CardBrandImages?,
    filterBy = CardTokenFilter,
    orderBy = CardTokenOrder,
    limitTokens = Int?,
    style = ClickOnceStyle,
    onOnceCardClick = (() -> Unit)?,
    onPreRenderTokens = ((List<CardToken>) -> List<CardTokenMapping>)?,
    transactionInitiatorType = TransactionInitiatorType?
)
```

Assign `gatewayTokenId` and `externalTokenId` on the config instance after you create it. They aren't constructor parameters of `ClickOnceComponentConfig`. Colour and text overrides on `style` use `ClickOnceStyle.ColorStyles` and `ClickOnceStyle.TextStyles`.

| Property | Description |
|  --- | --- |
| `headerTitle`String | Title text displayed at the top of the component. Defaults to the default header title. |
| `submitText`String? | Text displayed on the submit button. |
| `submitProcessingText`String? | Text displayed during processing/loading state. Defaults to the default processing text. |
| `selectCardText`String | Text for card selection prompt. Defaults to "Select Card". |
| `expiredText`String? | Text displayed for expired cards. |
| `validThruText`String? | Text displayed before expiry date (e.g., "Valid Thru"). Defaults to "Valid Thru". |
| `hideCardBrandLogo`Boolean | Whether to hide the card brand logo/icon. Defaults to `false`. |
| `disableCardSelection`Boolean | Whether to disable card selection functionality. Defaults to `false`. |
| `isRenderLastPurchaseCard`Boolean | Whether to render cards used for last purchase. Defaults to `true`. |
| `isRenderLastPayoutCard`Boolean | Whether to display cards previously used for successful payouts. When `true`, cards with a `lastSuccessfulPayoutDate` will be shown even if they haven't been used for purchases. Recommended for payout flows (`CardIntentType.Payout`) to show recipients their familiar payout cards. Defaults to `true`. |
| `isCvcRequired`Boolean | Always required for `ClickOnceComponentConfig`. The constructor still accepts this parameter, but construction always sets it to `true` even if you pass `false`. Use `onPreRenderTokens` and `CardTokenMapping.isCvcRequired` for a per-token override. For optional CVC at config level, use `ComponentType.CLICK_ONCE_STANDALONE` with `ClickOnceStandaloneComponentConfig`. |
| `useTransparentCardBrandImage`Boolean | Whether to use transparent background for card brand images. Defaults to `true`. |
| `isProcessNextStepOnCardClick`Boolean | Whether to automatically process next step when card is clicked. Defaults to `true`. |
| `cvcComponentConfig`CardCvcComponentConfig? | Configuration for the CVC input component. |
| `cardSubmitComponentConfig`CardSubmitComponentConfig? | Configuration for the card submit component. |
| `notificationConfig`NotificationConfig | Configuration for notifications display. Defaults to default configuration. |
| `cardBrandImages`CardBrandImages? | Custom card brand images configuration. |
| `filterBy`CardTokenFilter | Filter criteria for card tokens. Defaults to default filter. |
| `orderBy`CardTokenOrder | Sorting/ordering criteria for card tokens. Defaults to default order. |
| `limitTokens`Int? | Maximum number of tokens to display (null = no limit). |
| `style`ClickOnceStyle | Visual styling configuration for the component. Defaults to default style. Override colours with `ClickOnceStyle.ColorStyles` and text with `ClickOnceStyle.TextStyles`. |
| `onOnceCardClick`(() -> Unit)? | Callback triggered when a card is clicked. |
| `onPreRenderTokens`((List<CardToken>) -> List<CardTokenMapping>)? | Callback that returns which tokens to show and an optional per-token CVC requirement. It does not accept a custom display label. The UI formats the masked PAN from `last4`. |
| `transactionInitiatorType`TransactionInitiatorType? | Optional. Use `CIT` for customer-initiated payments and `MIT` for merchant-initiated payments. For `CIT` when the card intent is not payout, click-once requests PAN tokens only (it excludes DPANs). MIT and payout flows don't apply that filter. |
| `gatewayTokenId`String? | The gateway token ID of a saved card. When set, click-once loads that token directly and the shopper doesn't select a card from the list. Store the value from `onPostTokenisation` (e.g., on a new-card submit) and pass it here on a later click-once checkout. If both `gatewayTokenId` and `externalTokenId` are set, `gatewayTokenId` takes precedence. Set this on the config after you construct it, for example `config.apply { gatewayTokenId = "…" }`. |
| `externalTokenId`String? | External token identifier. Use this to load a specific token when you have a token ID from an external system and aren't using `gatewayTokenId`. Set this on the config after you construct it, for example `config.apply { externalTokenId = "…" }`. |


## Callbacks

Set callbacks on the `ClickOnceComponentConfig` instance. Validation callbacks are inherited from `ClickOnceStandaloneComponentConfig`. Click-once adds `onOnceCardClick` and `onPreRenderTokens`. Use `ValidationResult`, `CardToken`, and `CardTokenMapping` from `com.pxp.checkout.models`.

```kotlin
// ClickOnceComponentConfig (open class) — callback properties include:

// Inherited validation callbacks (ClickOnceStandaloneComponentConfig):
var onValidationPassed: ((List<ValidationResult>) -> Unit)? = null
var onValidationFailed: ((List<ValidationResult>) -> Unit)? = null
var onTriggerFieldValidation: ((ValidationResult) -> Unit)? = null

// Click-once specific:
var onOnceCardClick: (() -> Unit)? = null
var onPreRenderTokens: ((List<CardToken>) -> List<CardTokenMapping>)? = null
```

| Callback | Description |
|  --- | --- |
| `onValidationPassed: ((List<ValidationResult>) -> Unit)?` | Event handler for when validation passes. On `ClickOnceStandaloneComponentConfig` (via `ClickOnceComponentConfig`). |
| `onValidationFailed: ((List<ValidationResult>) -> Unit)?` | Event handler for when validation fails. On `ClickOnceStandaloneComponentConfig` (via `ClickOnceComponentConfig`). |
| `onTriggerFieldValidation: ((ValidationResult) -> Unit)?` | Event handler for when field validation is triggered individually. On `ClickOnceStandaloneComponentConfig` (via `ClickOnceComponentConfig`). |
| `onOnceCardClick: (() -> Unit)?` | Event handler triggered when a card is clicked. |
| `onPreRenderTokens: ((List<CardToken>) -> List<CardTokenMapping>)?` | Event handler for custom token processing before rendering. Return `CardTokenMapping(id, isCvcRequired)` for each token to show. The UI formats the masked PAN from `last4`. |


For more information about callbacks, see [Events](/guides/checkout/components/android/card/events).

When using click-once with card submit, you can leverage the `onCustomValidation` callback via `cardSubmitComponentConfig` to implement custom business rule validation before payment submission. See [Card submit](/guides/checkout/components/android/card/card-submit) for details.

**Payout support:** The click-once component supports card payouts (also called disbursements or withdrawals) where funds are sent from your merchant account to a cardholder's card. This is commonly used for:

- Marketplace seller payments
- Insurance claim settlements
- Refunds and reimbursements
- Competition prizes and rewards


When using `TransactionIntentData(card = CardIntentType.Payout)`, configure `isRenderLastPayoutCard = true` to display cards previously used for successful payouts, providing a familiar payout experience for returning recipients.

## Example

### Pay with a stored gateway token

Use `gatewayTokenId` when you already know which saved card to charge. Capture the ID from `onPostTokenisation` when the card is first tokenised, then pass it into click-once. Click-once loads that token directly, so the shopper doesn't select a card from the list. Pre-bound load via `gatewayTokenId` or `externalTokenId` does not apply list filtering such as `filterBy.excludeExpiredTokens`.

```kotlin
import com.pxp.checkout.components.cardcvc.CardCvcComponentConfig
import com.pxp.checkout.components.cardsubmit.CardSubmitComponentConfig
import com.pxp.checkout.components.clickonce.ClickOnceComponent
import com.pxp.checkout.components.clickonce.ClickOnceComponentConfig
import com.pxp.checkout.services.models.cardtoken.CardTokenisationResult
import com.pxp.checkout.types.ComponentType

// First payment / new card: store the gateway token ID after tokenisation
val submitConfig = CardSubmitComponentConfig().apply {
    // ...newCardComponent and other submit config
    onPostTokenisation = { result ->
        when (result) {
            is CardTokenisationResult.Success -> {
                // Store result.gatewayTokenId on your backend. Pass it as gatewayTokenId on a later
                // click-once config so the shopper pays with that token without selecting it.
                saveGatewayTokenId(result.gatewayTokenId)
            }
            is CardTokenisationResult.Failure -> {
                Log.e("Checkout", "Tokenisation failed: ${result.errorReason}")
            }
        }
    }
}

// Later checkout: charge that token without card selection
val storedGatewayTokenId = getStoredGatewayTokenId() // e.g. "123123-123123-123123-123123"

val config = ClickOnceComponentConfig(
    isCvcRequired = true,
    cvcComponentConfig = CardCvcComponentConfig(
        label = "CVC",
        placeholder = "123",
    ),
    cardSubmitComponentConfig = CardSubmitComponentConfig().apply {
        buttonText = "Pay Now"
        onPostAuthorisation = { result ->
            Log.d("Checkout", "Payment completed: ${result.merchantTransactionId}")
            navigateToSuccess()
        }
    },
).apply {
    gatewayTokenId = storedGatewayTokenId
}

val clickOnceComponent = checkout.createComponent<ClickOnceComponent>(
    type = ComponentType.CLICK_ONCE,
    config = config,
)
```

### General configuration

`onPreRenderTokens` returns which tokens to show and an optional per-token CVC requirement. It does not accept a custom display label. The UI formats the masked PAN from `last4`.

```kotlin
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.sp
import com.pxp.checkout.components.cardcvc.CardCvcComponentConfig
import com.pxp.checkout.components.cardsubmit.CardSubmitComponentConfig
import com.pxp.checkout.components.clickonce.ClickOnceComponent
import com.pxp.checkout.components.clickonce.ClickOnceComponentConfig
import com.pxp.checkout.models.CardTokenFilter
import com.pxp.checkout.models.CardTokenMapping
import com.pxp.checkout.models.CardTokenOrder
import com.pxp.checkout.models.LastUsageField
import com.pxp.checkout.models.LastUsageOrderConfig
import com.pxp.checkout.models.SortDirection
import com.pxp.checkout.services.models.cardtoken.CardTokenisationResult
import com.pxp.checkout.styles.ClickOnceStyle
import com.pxp.checkout.types.ComponentType

// Optional: Create custom CVC configuration
val cvcConfig = CardCvcComponentConfig(
    label = "CVC",
    placeholder = "123",
    showMaskToggle = true
)

// Optional: Create custom submit configuration
val submitConfig = CardSubmitComponentConfig().apply {
    buttonText = "Pay Now"
    loadingText = "Processing..."
    onPostTokenisation = { result ->
        when (result) {
            is CardTokenisationResult.Success -> {
                // Store result.gatewayTokenId on your backend. Pass it as gatewayTokenId on a later
                // click-once config so the shopper pays with that token without selecting it.
                saveGatewayTokenId(result.gatewayTokenId)
            }
            is CardTokenisationResult.Failure -> {
                Log.e("Checkout", "Tokenisation failed: ${result.errorReason}")
            }
        }
    }
}

// Optional: Create custom filtering and ordering
val tokenFilter = CardTokenFilter(
    excludeExpiredTokens = true,
    allowedSchemes = listOf("VISA", "MASTERCARD"), // null means no scheme restriction
)

val tokenOrder = CardTokenOrder(
    lastUsageDate = LastUsageOrderConfig(
        orderByField = LastUsageField.LATEST,
        direction = SortDirection.DESCENDING,
    ),
)

// Optional: Create custom styling
val customStyle = ClickOnceStyle(
    colors = ClickOnceStyle.ColorStyles(
        primaryColor = Color.Blue,
        surfaceColor = Color.White,
        onSurfaceColor = Color.Black,
    ),
    textStyles = ClickOnceStyle.TextStyles(
        cardNumberStyle = TextStyle(
            fontSize = 16.sp,
            fontWeight = FontWeight.SemiBold,
        ),
    ),
)

val config = ClickOnceComponentConfig(
    // Display text configuration
    headerTitle = "Select Payment Method",
    submitText = "Pay Now",
    submitProcessingText = "Processing Payment...",
    selectCardText = "Choose your card",
    validThruText = "Valid Thru",
    
    // Behaviour configuration
    hideCardBrandLogo = false,
    disableCardSelection = false,
    isRenderLastPurchaseCard = true,
    isRenderLastPayoutCard = true,
    isCvcRequired = true,
    useTransparentCardBrandImage = true,
    isProcessNextStepOnCardClick = true,
    
    // Component integrations
    cvcComponentConfig = cvcConfig,
    cardSubmitComponentConfig = submitConfig,
    
    // Data management
    filterBy = tokenFilter,
    orderBy = tokenOrder,
    limitTokens = 5,
    
    // Styling
    style = customStyle,
    
    // Event handlers
    onOnceCardClick = {
        println("Card clicked for quick payment")
    },
    onPreRenderTokens = { tokens ->
        tokens.map { token ->
            CardTokenMapping(
                id = token.id,
                isCvcRequired = null, // omit override; use component default, or set true/false per token
            )
        }
    }
)

val clickOnceComponent = checkout.createComponent<ClickOnceComponent>(
    type = ComponentType.CLICK_ONCE,
    config = config,
)
```

To sort by expiry date instead, pass an `OrderByDirectionConfig` from `com.pxp.checkout.models`:

```kotlin
val tokenOrderByExpiry = CardTokenOrder(
    expiryDate = OrderByDirectionConfig(
        direction = SortDirection.ASCENDING,
    ),
)
```

To show only some tokens, filter before you map:

```kotlin
onPreRenderTokens = { tokens ->
    tokens
        .filter { !it.isExpired }
        .map { CardTokenMapping(id = it.id) }
}
```

### Payout/disbursement flow

Use the click-once component to send funds to a cardholder's card (common for marketplace payouts, refunds, or prize disbursements). Set transaction data when building `PxpCheckout` (or your `PxpSdkConfig`), before creating components.

```kotlin
import com.pxp.PxpCheckout
import com.pxp.checkout.components.cardsubmit.CardSubmitComponentConfig
import com.pxp.checkout.components.clickonce.ClickOnceComponent
import com.pxp.checkout.components.clickonce.ClickOnceComponentConfig
import com.pxp.checkout.models.CardIntentType
import com.pxp.checkout.models.CardTokenOrder
import com.pxp.checkout.models.EntryType
import com.pxp.checkout.models.Environment
import com.pxp.checkout.models.LastUsageField
import com.pxp.checkout.models.LastUsageOrderConfig
import com.pxp.checkout.models.PxpSdkConfig
import com.pxp.checkout.models.SortDirection
import com.pxp.checkout.models.TransactionData
import com.pxp.checkout.models.TransactionIntentData
import com.pxp.checkout.types.ComponentType

val transactionData = TransactionData(
    amount = 150.00,
    currency = "USD",
    entryType = EntryType.Ecom,
    intent = TransactionIntentData(card = CardIntentType.Payout),
    merchant = "{merchantId}",
    merchantTransactionId = "payout-${System.currentTimeMillis()}",
    merchantTransactionDate = { java.time.Instant.now().toString() },
)

val sdkConfig = PxpSdkConfig(
    environment = Environment.TEST,
    session = sessionConfig,
    transactionData = transactionData,
    clientId = "your-client-id",
    ownerType = "MerchantGroup",
    ownerId = "UnityGroup",
)

val checkout = PxpCheckout.builder()
    .withConfig(sdkConfig)
    .withContext(context)
    .build()

val config = ClickOnceComponentConfig(
    headerTitle = "Select payout card",
    submitText = "Send funds",
    submitProcessingText = "Processing payout...",
    
    // Enable payout-specific features
    isRenderLastPayoutCard = true,  // Show cards used for previous payouts
    isRenderLastPurchaseCard = false,  // Optionally hide purchase-only cards
    
    // Sort by most recent payout activity
    orderBy = CardTokenOrder(
        lastUsageDate = LastUsageOrderConfig(
            orderByField = LastUsageField.PAYOUT_DATE,
            direction = SortDirection.DESCENDING,
        ),
    ),
    
    isCvcRequired = true,
    limitTokens = 5,
    
    cardSubmitComponentConfig = CardSubmitComponentConfig().apply {
        onPreAuthorisation = { data ->
            // Add any payout-specific data
            TransactionInitiationData(
                riskScreeningData = RiskScreeningData(
                    performRiskScreening = true,
                    userIp = "192.168.1.100",
                    account = RiskScreeningAccount(
                        id = "recipient_12345",
                        creationDateTime = "2024-01-15T10:30:00.000Z"
                    ),
                    fulfillments = listOf(
                        RiskScreeningFulfillment(
                            type = FulfillmentType.SHIPPED,
                            recipientPerson = RiskScreeningRecipientPerson(
                                phoneNumber = "+1234567890"
                            )
                        )
                    )
                )
            )
        }
        onPostAuthorisation = { result ->
            Log.d("Payout", "Completed: ${result.merchantTransactionId}")
            navigateToPayoutConfirmation()
        }
    },
    
    onOnceCardClick = {
        Log.d("Payout", "Card selected for payout")
    }
)

val clickOnceComponent = checkout.createComponent<ClickOnceComponent>(
    type = ComponentType.CLICK_ONCE,
    config = config,
)
```

When using `CardIntentType.Payout`, funds move from your merchant account to the cardholder's card. Ensure you have sufficient balance in your account and use appropriate messaging ("withdraw", "receive", "send to your card"). Note that not all cards support payouts.