Skip to content

Cards

Accept card payments with 3D Secure authentication, automatic validation, and one-click payments for returning customers.

Overview

Card payments are automatically included in the drop-in when enabled in your session. The drop-in handles all card field rendering, validation, 3D Secure authentication, and payment processing automatically.

Key benefits

Card payments in Drop-in give you:

  • Card fields appear automatically in the drop-in when cards are enabled in your session configuration.
  • The drop-in handles all card setup, so you don't need card-specific code.
  • Card payments use the same onSuccess and onError callbacks as other payment methods for a unified integration.
  • Automatic field validation runs for card number, expiry date, and CVC.
  • 3D Secure authentication is handled automatically with native Android UI.
  • Returning customers can use saved cards when card-on-file is enabled.
  • PCI DSS Level 1 compliance applies, with no card data stored on your server.

How it works

When a customer pays with a card:

  1. The customer taps Card in the payment options list. The card form appears.
  2. The customer enters their card number, expiry date, and CVC.
  3. The drop-in validates the card details in real time.
  4. The customer taps Pay and 3D Secure authentication begins (if required).
  5. The customer completes authentication in the native Android UI.
  6. Unity processes the payment.
  7. Your onSuccess callback fires.

Configuration

Use methodConfig.card to control which card sections appear in Drop-in, and methodConfig.global for card networks and consent. For manual card funding-source filtering, use CheckoutDropInConfig.restrictions or session card restrictions rather than Google Pay-only global settings.

Card display properties

The following properties are available through DropInCardConfig:

Property Description
showCOF
Boolean?
Controls whether the card-on-file (saved cards) section and its submit button are created. Defaults to true when omitted (null). When true, card-on-file is created only if the session allows cards and onGetShopper returns a shopper with a non-empty id. After creation, Drop-in shows the following:

  • Section header and COF panel: shown while tokens are loading or when cardTokens is non-empty.
  • Token list: shown only when cardTokens is non-empty.
showNewCard
Boolean?
Controls whether the new card form and related billing address, store-card consent checkbox (when the site asks for consent), and new-card submit button are created. Defaults to true when omitted (null).

Both flags are optional. Omitted values resolve to true, so both sections are shown unless you opt out. The Card payment method panel is visible when either resolved flag is true (showCOF || showNewCard). When both are false, Drop-in omits the entire Card panel and doesn't create card components.

These flags control creation and rendering of card UI inside Drop-in. They don't change session funding eligibility. Keep cards enabled in the session when you expect the Card payment method to appear.

How Drop-in collects consent to store a new card for card-on-file is controlled by your Unity Portal site configuration, not by a property on CheckoutDropInConfig. Drop-in reads authenticationConfiguration.storeCardConsent when create() fetches the checkout Drop-in site configuration.

The site can return one of the following values:

Site value Consent UI New card stored for card-on-file
AskCard consent checkbox when showNewCard is enabled and onGetShopper returns a non-empty shopper idOnly when the checkbox is checked, or when there's no checkbox and onGetConsent returns true for PaymentMethod.CARD
DontAskHiddenNever stored through the Drop-in consent flow
ConsentAlreadyObtainedHiddenAlways stored when a non-empty shopper id is present (Drop-in grants consent at tokenisation)

Use ConsentAlreadyObtained when the shopper has already agreed to store cards outside Drop-in (e.g., account registration or app settings). Drop-in doesn't show a consent checkbox and doesn't require onGetConsent for card storage in that mode.

Regardless of site mode, you still need:

  • A non-empty Shopper.id from onGetShopper for token vault storage and card-on-file.
  • showNewCard resolving to true if the shopper should pay with a new card that can be stored.
  • showCOF resolving to true if saved cards should appear and, after a successful stored new-card payment, Drop-in should refresh the card-on-file list.

Don't set storeCardConsent on the Android SDK config. Configure it in the Unity Portal for your site.

Settings used from global configuration

The following properties in DropInGlobalConfig also apply to card payments:

Property Description
acceptedCardNetworks
List<CardNetworks>?
Which card brands to accept through card payments. Falls back to session configuration if not specified.

Possible values:
  • CardNetworks.VISA
  • CardNetworks.MASTERCARD
  • CardNetworks.AMERICAN_EXPRESS
  • CardNetworks.UNION_PAY
  • CardNetworks.DINERS
  • CardNetworks.JCB
  • CardNetworks.DISCOVER
onGetConsent
(paymentMethod: PaymentMethod) -> Boolean
Returns whether the shopper has consented for new card tokenisation when Drop-in has no visible card consent component. Drop-in wires onGetConsent(PaymentMethod.CARD) to onPreTokenisation on the new card submit component only. Card-on-file (COF) submit doesn't invoke onGetConsent. The SDK renders the card consent checkbox only when showNewCard is true, a shopper ID is available, and the site storeCardConsent value is Ask. When the site is ConsentAlreadyObtained, Drop-in stores the card without calling onGetConsent. When the site is DontAsk, Drop-in doesn't store the card through this consent flow. See Store-card consent and Events — onGetConsent.

In Drop-in, methodConfig.global.allowedCardFundingSource and allowedIssuerCountryCodes apply to Google Pay only. They don't filter manual new-card entry. For card funding-source filtering, use CheckoutDropInConfig.restrictions with RestrictionsCard.fundingSources, or session-level card restrictions.

Complete example

This example shows a full card configuration with display options and global settings that apply to cards:

methodConfig = DropInMethodConfig(
    // Global settings that apply to card payments
    global = DropInGlobalConfig(
        // Restrict to specific card networks
        acceptedCardNetworks = listOf(
            CardNetworks.VISA,
            CardNetworks.MASTERCARD,
            CardNetworks.AMERICAN_EXPRESS
        ),

        // Supply consent for new card tokenisation when no consent UI is shown
        onGetConsent = { paymentMethod ->
            paymentMethod == PaymentMethod.CARD
        }
    ),

    // Show both card-on-file and new card entry
    card = DropInCardConfig(
        showCOF = true,
        showNewCard = true
    )
)

Card display examples

Omit card, or leave both properties unset, to show card-on-file and new card entry by default:

methodConfig = DropInMethodConfig(
    // card omitted — both COF and new card are shown
)

Show saved cards only for returning shoppers:

methodConfig = DropInMethodConfig(
    card = DropInCardConfig(
        showCOF = true,
        showNewCard = false
    )
),
onGetShopper = {
    Shopper(id = "shopper-123") // shopper.id required for COF
}

Show new card entry only, for example when the shopper is anonymous:

methodConfig = DropInMethodConfig(
    card = DropInCardConfig(
        showCOF = false,
        showNewCard = true
    )
)

Hide the entire card panel, for example in a wallet-only checkout:

methodConfig = DropInMethodConfig(
    card = DropInCardConfig(
        showCOF = false,
        showNewCard = false
    )
)

Card requirements

Card payments require the following to function correctly:

  • Android compatibility: Android 7.0 (API level 24) or higher.
  • HTTPS: Your backend endpoints must be served over HTTPS.
  • Unity Portal configuration: Cards must be enabled and configured in the Unity Portal.
  • Entry type: Cards support Ecom and Moto entry types.
  • 3D Secure: Your merchant account must be configured for 3D Secure authentication.

One-click and card-on-file flows require the shopper to have previously authorised your merchant account where scheme rules apply. Authorisations must be captured within the time window specified by your payment scheme (typically 7-30 days).

Implementation

Card payments work through the standard Drop-in implementation. Initialise CheckoutDropIn, call create() from a coroutine, and render with CheckoutDropIn.Content():

import android.util.Log
import android.widget.Toast
import com.pxp.checkout.checkoutdropin.CheckoutDropIn
import com.pxp.checkout.checkoutdropin.types.CheckoutDropInConfig
import com.pxp.checkout.checkoutdropin.types.DropInSubmitResult
import com.pxp.checkout.checkoutdropin.types.PaymentMethod
import com.pxp.checkout.exceptions.BaseSdkException
import com.pxp.checkout.models.CardIntentType
import com.pxp.checkout.models.DropInTransactionData
import com.pxp.checkout.models.DropInTransactionIntentData
import com.pxp.checkout.models.Environment
import com.pxp.checkout.models.EntryType
import com.pxp.checkout.models.SessionConfig
import com.pxp.checkout.services.models.transaction.Shopper
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import java.time.Instant
import java.util.UUID

@Composable
fun CheckoutScreen() {
    val context = LocalContext.current
    var sessionConfig by remember { mutableStateOf<SessionConfig?>(null) }
    var isLoading by remember { mutableStateOf(true) }

    // Fetch session from your backend and map it to SessionConfig.
    // See Quickstart for fetchSessionFromBackend() and toSessionConfig().
    LaunchedEffect(Unit) {
        try {
            sessionConfig = fetchSessionFromBackend()
        } catch (e: Exception) {
            Log.e("Checkout", "Error creating session", e)
        } finally {
            isLoading = false
        }
    }

    val checkoutDropIn = remember(sessionConfig) {
        sessionConfig?.let { session ->
            CheckoutDropIn.initialize(
                context = context,
                config = CheckoutDropInConfig(
                    environment = Environment.TEST,
                    session = session,
                    ownerType = "MerchantGroup",
                    ownerId = "MERCHANT-1",
                    transactionData = DropInTransactionData(
                        currency = "GBP",
                        amount = 99.99,
                        entryType = EntryType.Ecom,
                        intent = DropInTransactionIntentData(
                            card = CardIntentType.Authorisation
                        ),
                        merchant = "Demo Store",
                        merchantTransactionId = UUID.randomUUID().toString(),
                        merchantTransactionDate = { Instant.now().toString() }
                    ),
                    onGetShopper = {
                        // Provide shopper ID for vaulting
                        Shopper(id = "shopper-123")
                    },
                    onSuccess = { result: DropInSubmitResult ->
                        Log.d("Checkout", "Card payment successful!")
                        Log.d("Checkout", "System transaction ID: ${result.systemTransactionId}")
                        Log.d("Checkout", "Payment method: ${result.paymentMethod}")

                        // CRITICAL: Verify on backend
                        verifyPaymentOnBackend(result)
                    },
                    onError = { paymentMethod: PaymentMethod?, error: BaseSdkException ->
                        Log.e(
                            "Checkout",
                            "Card payment failed [${paymentMethod?.value}]: ${error.errorCode} — ${error.message}"
                        )
                        Toast.makeText(
                            context,
                            "Payment failed: ${error.message}",
                            Toast.LENGTH_LONG
                        ).show()
                    }
                )
            )
        }
    }

    LaunchedEffect(checkoutDropIn) {
        checkoutDropIn?.create()
    }

    // Render Drop-in (shows loading until create() finishes)
    if (isLoading && checkoutDropIn == null) {
        // Optional: show your own loading UI while the session request is in flight
    } else {
        checkoutDropIn?.Content(modifier = Modifier.fillMaxWidth())
    }
}

Session configuration (backend)

Enable cards in your session request with a card intent. The Sessions API returns allowedFundingTypes in the response. Map that response into SessionConfig on the client. Don't put allowedFundingTypes in the create-session request body.

// BACKEND: Create a session with cards enabled
const sessionRequest = {
  merchant: "MERCHANT-1",
  site: "SITE-1",
  sessionTimeout: 120,
  merchantTransactionId: crypto.randomUUID(),
  transactionMethod: {
    intent: {
      card: "Authorisation"  // or "Purchase"
    }
  },
  amounts: {
    currencyCode: "GBP",
    transactionValue: 99.99
  },
  allowTransaction: true,
  serviceType: "CheckoutDropIn"
};

A successful response includes session credentials and funding configuration such as allowedFundingTypes.cards (required for the Card panel; may be an empty array) and optional allowedFundingTypes.cardSchemes. Map the response into SessionConfig on the client. cardSchemes alone doesn't enable the card UI. See Implementation for the full session request and response mapping.

Common card payment flows

Drop-in supports these common e-commerce card flows through DropInTransactionIntentData.card. Configure the intent with CardIntentType:

Two-step payment: authorise now, capture later (within scheme-specific time windows).

import com.pxp.checkout.models.CardIntentType
import com.pxp.checkout.models.DropInTransactionData
import com.pxp.checkout.models.DropInTransactionIntentData
import com.pxp.checkout.models.EntryType
import java.time.Instant
import java.util.UUID

transactionData = DropInTransactionData(
    currency = "GBP",
    amount = 149.99,
    entryType = EntryType.Ecom,
    intent = DropInTransactionIntentData(
        card = CardIntentType.Authorisation  // Confirm Payment flow
    ),
    merchant = "Demo Store",
    merchantTransactionId = UUID.randomUUID().toString(),
    merchantTransactionDate = { Instant.now().toString() }
)

Use this flow for:

  • Physical products (capture on shipment)
  • Inventory validation needed
  • Final amount may change (shipping, taxes)
  • Complex order workflows

CardIntentType also includes Verification, EstimatedAuthorisation, and Payout. Use those only when your Unity Portal setup and backend support the corresponding card flow. See the session intent table in Implementation.

Handling responses

Card callback data

When a card payment succeeds, your onSuccess callback receives the same standard result as other payment methods:

onSuccess = { result: DropInSubmitResult ->
    Log.d("Checkout", "Payment details:")
    Log.d("Checkout", "- System transaction ID: ${result.systemTransactionId}")
    Log.d("Checkout", "- Merchant transaction ID: ${result.merchantTransactionId}")
    Log.d("Checkout", "- Payment method: ${result.paymentMethod}") // "Card"

    // Note: Amount, currency, card details must be retrieved from backend
    // 3D Secure authentication data is handled internally
}

Error handling

Handle card errors with both error.errorCode and error.message. Drop-in card failures can surface codes such as SDK1113 (authentication failed), SDK1114 (authorisation failed), and SDK1115 (card payment failed):

import com.pxp.checkout.checkoutdropin.types.PaymentMethod
import com.pxp.checkout.exceptions.BaseSdkException
import com.pxp.checkout.exceptions.SdkErrorCodes

onError = { paymentMethod: PaymentMethod?, error: BaseSdkException ->
    Log.e(
        "Checkout",
        "Error [${paymentMethod?.value}]: ${error.errorCode} — ${error.message}"
    )

    when (error.errorCode) {
        SdkErrorCodes.CHECKOUT_DROPIN_AUTHENTICATION_FAILED -> {
            // SDK1113 — 3DS / authentication failed
            Toast.makeText(
                context,
                "Authentication failed. Please try again.",
                Toast.LENGTH_LONG
            ).show()
        }
        SdkErrorCodes.CHECKOUT_DROPIN_AUTHORISATION_FAILED -> {
            // SDK1114 — authorisation failed
            Toast.makeText(
                context,
                "Authorisation failed. Please try again or use a different card.",
                Toast.LENGTH_LONG
            ).show()
        }
        SdkErrorCodes.CHECKOUT_DROPIN_CARD_PAYMENT_FAILED -> {
            // SDK1115 — card declined or processing failure
            Toast.makeText(
                context,
                "Card payment failed. Please try a different card.",
                Toast.LENGTH_LONG
            ).show()
        }
        else -> {
            // Fall back to message parsing for provider-specific detail
            when {
                error.message?.contains("declined", ignoreCase = true) == true -> {
                    Toast.makeText(
                        context,
                        "Card declined. Please try a different card.",
                        Toast.LENGTH_LONG
                    ).show()
                }
                error.message?.contains("insufficient", ignoreCase = true) == true -> {
                    Toast.makeText(
                        context,
                        "Insufficient funds. Please use a different card.",
                        Toast.LENGTH_LONG
                    ).show()
                }
                error.message?.contains("expired", ignoreCase = true) == true -> {
                    Toast.makeText(
                        context,
                        "Card expired. Please use a different card.",
                        Toast.LENGTH_LONG
                    ).show()
                }
                error.message?.contains("invalid", ignoreCase = true) == true -> {
                    Toast.makeText(
                        context,
                        "Invalid card details. Please check and try again.",
                        Toast.LENGTH_LONG
                    ).show()
                }
                else -> {
                    Toast.makeText(
                        context,
                        "Payment failed: ${error.message}",
                        Toast.LENGTH_LONG
                    ).show()
                }
            }
        }
    }
}

Common error scenarios

The following table describes common card error scenarios:

ScenarioHow to detectRecommended action
Card declinederror.errorCode is SDK1115, or error.message contains "declined"Suggest trying a different card
Insufficient fundserror.message contains "insufficient"Suggest using a different card or payment method
Card expirederror.message contains "expired"Request valid card details
Invalid carderror.message contains "invalid"Ask the customer to check card details
3D Secure failederror.errorCode is SDK1113, or error.message contains "3DS" or "authentication"Suggest trying again or contacting the bank
Authorisation failederror.errorCode is SDK1114Suggest trying again or using a different card
Network errorerror.message contains "network" or "timeout"Retry payment after a brief delay

Use error.errorCode for programmatic handling of Drop-in failures (SDK1113, SDK1114, SDK1115, and other SDK codes). Use error.message as additional detail for provider-specific or user-facing text. For production apps, implement robust error handling with retry logic and user-friendly messaging.

Backend verification

Always verify card payments on your backend to ensure payment success before fulfilling orders. In a Compose screen, launch verification with rememberCoroutineScope():

import android.util.Log
import android.widget.Toast
import androidx.compose.runtime.rememberCoroutineScope
import com.pxp.checkout.checkoutdropin.types.DropInSubmitResult
import io.ktor.client.call.body
import io.ktor.http.ContentType
import io.ktor.http.contentType
import kotlinx.coroutines.launch

val scope = rememberCoroutineScope()

onSuccess = { result: DropInSubmitResult ->
    // Send to backend for verification. apiClient is your Ktor HttpClient.
    scope.launch {
        try {
            val response = apiClient.post("/api/verify-payment") {
                contentType(ContentType.Application.Json)
                setBody(mapOf(
                    "systemTransactionId" to result.systemTransactionId,
                    "merchantTransactionId" to result.merchantTransactionId
                ))
            }

            if (response.status.value == 200) {
                val verified = response.body<VerificationResponse>()
                if (verified.success) {
                    // Go to success screen
                    navController.navigate("success?orderId=${verified.orderId}")
                } else {
                    Toast.makeText(
                        context,
                        "Payment verification failed",
                        Toast.LENGTH_LONG
                    ).show()
                }
            }
        } catch (e: Exception) {
            Log.e("Checkout", "Verification error", e)
            Toast.makeText(
                context,
                "Failed to verify payment",
                Toast.LENGTH_LONG
            ).show()
        }
    }
}

Backend verification code

Use the following backend code to verify card transactions via the PXP API:

// BACKEND: Verify card payment
app.post('/api/verify-payment', async (req, res) => {
  const { systemTransactionId, merchantTransactionId } = req.body;

  try {
    // Query the PXP API to get transaction details
    const txnPath = `api/v1/transactions/${systemTransactionId}`;
    const { authHeader, requestId } = createAuthHeader(
      txnPath,
      '',
      process.env.PXP_TOKEN_ID,
      process.env.PXP_TOKEN_VALUE
    );

    const transaction = await fetch(
      `https://api-services.pxp.io/${txnPath}`,
      {
        headers: {
          'X-Client-Id': process.env.PXP_CLIENT_ID,
          'X-Request-Id': requestId,
          'Authorization': authHeader
        }
      }
    ).then(r => r.json());

    // Verify transaction state
    if (transaction.state !== 'Authorised' && transaction.state !== 'Captured') {
      return res.json({ success: false, error: 'Transaction not successful' });
    }

    // Verify merchant transaction ID matches
    if (transaction.merchantTransactionId !== merchantTransactionId) {
      return res.json({ success: false, error: 'Transaction ID mismatch' });
    }

    // Verify amount matches expected amount from your order records
    const order = await getOrderByMerchantTransactionId(merchantTransactionId);
    const txnAmount = transaction.amounts?.transactionValue || transaction.amount || 0;
    if (Math.abs(txnAmount - order.amount) > 0.01) {
      return res.json({ success: false, error: 'Amount mismatch' });
    }

    // Verify funding type is card
    const fundingType = transaction.fundingData?.fundingType ||
                       transaction.fundingType ||
                       'Unknown';
    if (fundingType !== 'Card') {
      return res.json({ success: false, error: 'Invalid funding type' });
    }

    // Fulfil order
    const orderId = await fulfillOrder(transaction);

    return res.json({ success: true, orderId });

  } catch (error) {
    console.error('Verification error:', error);
    return res.json({ success: false, error: 'Verification failed' });
  }
});

Advanced card flows

Card vaulting (one-click payment)

Card vaulting lets returning customers pay with a saved card without re-entering the full card number. When enabled, customers who have previously saved a card can select that card in Drop-in. CVC may still be required when isCvcRequired is true for the vaulted token.

How it works

Vaulting follows this sequence:

  1. The customer pays with a new card. Depending on site storeCardConsent, they either check the consent checkbox (Ask), you supply consent with onGetConsent when no checkbox is shown (Ask), or Drop-in stores the card because consent was already obtained outside Drop-in (ConsentAlreadyObtained). See Store-card consent.
  2. Unity vaults the card and returns a vault ID.
  3. On return visit, your backend creates a session with optional customerProfileId, and onGetShopper provides the shopper ID.
  4. Drop-in shows saved cards when tokens are available.
  5. The customer selects a saved card, enters CVC if required, and confirms payment.

Enable card vaulting

Card-on-file requires all of the following:

  • The session allows cards.
  • showCOF resolves to true (the default when omitted).
  • onGetShopper returns a shopper with a non-empty id.

Optional customerProfileId on the session request links the Unity session to a Customer Profile. It doesn't replace onGetShopper for card-on-file. See Implementation — Customer Profile.

Even when card-on-file is enabled, Drop-in shows the following:

  • Section header and COF panel: shown while tokens are loading or when cardTokens is non-empty.
  • Token list: shown only when cardTokens is non-empty.

Implement onGetShopper and keep card-on-file enabled:

import android.util.Log
import android.widget.Toast
import com.pxp.checkout.checkoutdropin.CheckoutDropIn
import com.pxp.checkout.checkoutdropin.types.CheckoutDropInConfig
import com.pxp.checkout.checkoutdropin.types.DropInMethodConfig
import com.pxp.checkout.checkoutdropin.types.DropInSubmitResult
import com.pxp.checkout.checkoutdropin.types.PaymentMethod
import com.pxp.checkout.checkoutdropin.types.methodconfigs.DropInCardConfig
import com.pxp.checkout.exceptions.BaseSdkException
import com.pxp.checkout.models.CardIntentType
import com.pxp.checkout.models.DropInTransactionData
import com.pxp.checkout.models.DropInTransactionIntentData
import com.pxp.checkout.models.Environment
import com.pxp.checkout.models.EntryType
import com.pxp.checkout.models.SessionConfig
import com.pxp.checkout.services.models.transaction.Shopper
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import java.time.Instant
import java.util.UUID

@Composable
fun CheckoutScreen() {
    val context = LocalContext.current
    var sessionConfig by remember { mutableStateOf<SessionConfig?>(null) }

    // Fetch session from backend
    LaunchedEffect(Unit) {
        sessionConfig = fetchSessionFromBackend()
    }

    val checkoutDropIn = remember(sessionConfig) {
        sessionConfig?.let { session ->
            CheckoutDropIn.initialize(
                context = context,
                config = CheckoutDropInConfig(
                    environment = Environment.TEST,
                    session = session,
                    ownerType = "MerchantGroup",
                    ownerId = "MERCHANT-1",
                    transactionData = DropInTransactionData(
                        currency = "GBP",
                        amount = 99.99,
                        entryType = EntryType.Ecom,
                        intent = DropInTransactionIntentData(
                            card = CardIntentType.Purchase
                        ),
                        merchant = "Demo Store",
                        merchantTransactionId = UUID.randomUUID().toString(),
                        merchantTransactionDate = { Instant.now().toString() }
                    ),
                    methodConfig = DropInMethodConfig(
                        card = DropInCardConfig(
                            showCOF = true,
                            showNewCard = true
                        )
                    ),
                    // REQUIRED: Provide shopper ID to enable card vaulting
                    onGetShopper = {
                        val user = getCurrentUser()
                        Shopper(id = user.shopperId) // e.g., Shopper(id = "shopper-123")
                    },
                    onSuccess = { result: DropInSubmitResult ->
                        verifyPaymentOnBackend(result)
                        navController.navigate("success")
                    },
                    onError = { paymentMethod: PaymentMethod?, error: BaseSdkException ->
                        Log.e(
                            "Checkout",
                            "Card payment failed [${paymentMethod?.value}]: ${error.errorCode} — ${error.message}"
                        )
                        Toast.makeText(
                            context,
                            "Payment failed: ${error.message}",
                            Toast.LENGTH_LONG
                        ).show()
                    }
                )
            )
        }
    }

    LaunchedEffect(checkoutDropIn) {
        checkoutDropIn?.create()
    }

    // Render Drop-in
    checkoutDropIn?.Content(modifier = Modifier.fillMaxWidth())
}

When showCOF is enabled and onGetShopper returns a shopper ID, the SDK automatically:

  • Fetches saved cards from the PXP API.
  • Enables saved-card payment when tokens are available.
  • Handles vault setup during the first payment when store-card consent is granted (checkbox, onGetConsent, or site ConsentAlreadyObtained).
  • After a successful new-card payment that stored the card, refreshes the card-on-file token list so the new card can appear without leaving checkout. Paying with an existing saved card doesn't trigger that refresh.

To hide saved cards while still allowing new card entry, set showCOF to false.

Card vaulting configuration

Card vaulting is enabled by implementing onGetShopper and keeping showCOF enabled. How consent is collected depends on site storeCardConsent (see Store-card consent).

When the site is Ask and Drop-in doesn't show a consent checkbox, supply consent with methodConfig.global.onGetConsent:

CheckoutDropInConfig(
    // ... other config
    onGetShopper = {
        val user = getCurrentUser()
        Shopper(id = user.shopperId)  // Required for vaulting
    },
    methodConfig = DropInMethodConfig(
        global = DropInGlobalConfig(
            onGetConsent = { paymentMethod ->
                // Applies to new card tokenisation (onPreTokenisation) only.
                // COF submit does not invoke onGetConsent.
                paymentMethod == PaymentMethod.CARD
            }
        ),
        card = DropInCardConfig(
            showCOF = true,
            showNewCard = true
        )
    )
)

When the site is ConsentAlreadyObtained, you don't need onGetConsent for card storage. Provide the shopper id and enable card-on-file and new card entry:

CheckoutDropInConfig(
    // ... other config
    onGetShopper = {
        Shopper(id = currentUser.shopperId)
    },
    methodConfig = DropInMethodConfig(
        card = DropInCardConfig(
            showCOF = true,
            showNewCard = true
        )
    )
    // No onGetConsent required when site storeCardConsent is ConsentAlreadyObtained
)

3D Secure authentication

3D Secure authentication is handled automatically by the drop-in. When a card requires 3D Secure, the drop-in:

  1. Detects that 3D Secure is required from the payment response.
  2. Launches the native Android 3D Secure UI.
  3. Guides the customer through authentication (OTP, biometric, and so on).
  4. Processes the authenticated payment.
  5. Fires your onSuccess callback on completion.

No additional code is required for 3D Secure authentication. The drop-in manages the entire flow automatically.

3D Secure UI is rendered using native Android components and adapts to the authentication method required by the card issuer (OTP, biometric, challenge questions, and so on). The UI is fully PCI DSS Level 1 compliant.

Recurring card payments

For subscriptions and recurring charges, use CardIntentType.Authorisation with card vaulting enabled:

import com.pxp.checkout.models.CardIntentType
import com.pxp.checkout.models.DropInTransactionData
import com.pxp.checkout.models.DropInTransactionIntentData
import com.pxp.checkout.models.EntryType
import java.time.Instant
import java.util.UUID

transactionData = DropInTransactionData(
    currency = "GBP",
    amount = 9.99,
    entryType = EntryType.Ecom,
    intent = DropInTransactionIntentData(
        card = CardIntentType.Authorisation  // Use Authorisation for recurring
    ),
    merchant = "Demo Store",
    merchantTransactionId = UUID.randomUUID().toString(),
    merchantTransactionDate = { Instant.now().toString() }
)

After the first payment, use the vaulted card token to process subsequent recurring payments via the PXP API without customer interaction.