{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading","br","details","admonition","tabs","tab"]},"type":"markdown"},"seo":{"title":"Cards","description":"Transform your commerce with PXP's unified platform—seamless payments, real-time insights, and global growth in one powerful integration.","lang":"en-UK","siteUrl":"https://developer.pxp.io","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"cards","__idx":0},"children":["Cards"]},{"$$mdtype":"Tag","name":"SubHeading","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Accept card payments with 3D Secure authentication, automatic validation, and one-click payments for returning customers."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-benefits","__idx":2},"children":["Key benefits"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Card fields appear automatically in the drop-in when cards are enabled in your session configuration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The drop-in handles all card setup, so you don't need card-specific code."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Card payments use the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," callbacks as other payment methods for a unified integration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Automatic field validation for card number, expiry date, and CVC."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["3D Secure authentication is handled automatically with native Android UI."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Returning customers can use one-click payments when their card is saved."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["PCI DSS Level 1 compliant, with no card data stored on your server."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":3},"children":["How it works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a customer pays with a card:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The customer taps \"Card\" in the payment options list. The card form appears."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The customer enters their card number, expiry date, and CVC."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The drop-in validates the card details in real time."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The customer taps \"Pay\" and 3D Secure authentication begins (if required)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The customer completes authentication in the native Android UI."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The payment is processed through Unity."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," callback fires."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuration","__idx":4},"children":["Configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Card-specific settings are configured through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["methodConfig.global"]}," in the Drop-in configuration. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DropInCardConfig"]}," class is currently an empty marker and doesn't have its own properties."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configuration-properties","__idx":5},"children":["Configuration properties"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following properties in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DropInGlobalConfig"]}," apply to card payments:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"50%","data-label":"Property"},"children":["Property "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"50%","data-label":"Description"},"children":["Description "]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["acceptedCardNetworks"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["List?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Which card brands to accept through card payments. Falls back to session configuration if not specified.",{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},"Possible values:",{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CardNetworks.VISA"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CardNetworks.MASTERCARD"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CardNetworks.AMERICAN_EXPRESS"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CardNetworks.UNION_PAY"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CardNetworks.DINERS"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CardNetworks.JCB"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CardNetworks.DISCOVER"]}]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedCardFundingSource"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["List?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Which funding types to accept (Credit, Debit, Prepaid).",{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},"Possible values:",{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CardFundingSource.CREDIT"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CardFundingSource.DEBIT"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CardFundingSource.PREPAID"]}]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedIssuerCountryCodes"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["List?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allowed card issuer countries as ISO country codes (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["listOf(\"GB\", \"US\", \"FR\")"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetConsent"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["(paymentMethod: PaymentMethod) -> Boolean"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Controls whether to show consent checkbox for card payments. Use this to enable card-on-file functionality."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"complete-example","__idx":6},"children":["Complete example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This example shows a full card configuration using global settings:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"methodConfig = DropInMethodConfig(\n // Global settings that apply to card payments\n global = DropInGlobalConfig(\n // Restrict to specific card networks\n acceptedCardNetworks = listOf(\n CardNetworks.VISA,\n CardNetworks.MASTERCARD,\n CardNetworks.AMERICAN_EXPRESS\n ),\n \n // Allow only credit and debit cards\n allowedCardFundingSource = listOf(\n CardFundingSource.CREDIT,\n CardFundingSource.DEBIT\n ),\n \n // Restrict to cards issued in specific countries\n allowedIssuerCountryCodes = listOf(\"GB\", \"US\", \"FR\"),\n \n // Control consent checkbox for cards\n onGetConsent = { paymentMethod ->\n // Show consent checkbox for cards to save payment method\n paymentMethod == PaymentMethod.CARD\n }\n ),\n \n // Card config is currently an empty marker\n card = DropInCardConfig()\n)\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"card-requirements","__idx":7},"children":["Card requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Card payments require the following to function correctly:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Android compatibility"]},": Android 8.0 (API level 26) or higher."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTPS"]},": Your backend endpoints must be served over HTTPS."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Unity Portal configuration"]},": Cards must be enabled and configured in the Unity Portal."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Entry type"]},": Cards support ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Ecom"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Moto"]}," entry types."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["3D Secure"]},": Your merchant account must be configured for 3D Secure authentication."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One-click payments require the shopper to have previously authorised your merchant account. Authorisations must be captured within the time window specified by your payment scheme (typically 7-30 days)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"implementation","__idx":8},"children":["Implementation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Card payments work through the standard implementation, with no card-specific code needed:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"import com.pxp.checkout.checkoutdropin.CheckoutDropIn\nimport com.pxp.checkout.checkoutdropin.types.CheckoutDropInConfig\nimport com.pxp.checkout.components.checkoutdropincomponent.CheckoutDropInComponent\nimport com.pxp.checkout.models.DropInTransactionData\nimport com.pxp.checkout.models.DropInTransactionIntentData\nimport com.pxp.checkout.models.Environment\nimport com.pxp.checkout.models.EntryType\nimport com.pxp.checkout.models.IntentType\nimport com.pxp.checkout.checkoutdropin.types.DropInSubmitResult\nimport com.pxp.checkout.exceptions.BaseSdkException\nimport androidx.compose.foundation.layout.fillMaxWidth\nimport androidx.compose.material.CircularProgressIndicator\nimport androidx.compose.runtime.*\nimport androidx.compose.ui.Modifier\nimport androidx.compose.ui.platform.LocalContext\n\n@Composable\nfun CheckoutScreen() {\n val context = LocalContext.current\n var sessionData by remember { mutableStateOf(null) }\n var checkoutDropInComponent by remember { mutableStateOf(null) }\n var isLoading by remember { mutableStateOf(true) }\n \n // Fetch session from backend\n LaunchedEffect(Unit) {\n try {\n val response = apiClient.post(\"/api/create-session\") {\n contentType(ContentType.Application.Json)\n }\n \n if (response.status.value == 200) {\n val result = response.body()\n if (result.success && result.data != null) {\n sessionData = result.data\n } else {\n Log.e(\"Checkout\", \"Failed to create session: ${result.error}\")\n }\n }\n } catch (e: Exception) {\n Log.e(\"Checkout\", \"Error creating session\", e)\n } finally {\n isLoading = false\n }\n }\n \n // Initialize Drop-in once session is loaded\n LaunchedEffect(sessionData) {\n sessionData?.let { session ->\n val checkoutDropIn = CheckoutDropIn.initialize(\n context = context,\n config = CheckoutDropInConfig(\n environment = Environment.TEST,\n session = session,\n ownerType = \"MerchantGroup\",\n ownerId = \"MERCHANT-1\",\n transactionData = DropInTransactionData(\n currency = \"GBP\",\n amount = 99.99,\n entryType = EntryType.Ecom,\n intent = DropInTransactionIntentData(\n card = IntentType.Authorisation\n ),\n merchant = \"Demo Store\",\n merchantTransactionId = { UUID.randomUUID().toString() },\n merchantTransactionDate = { Instant.now().toString() }\n ),\n onGetShopper = {\n // Provide shopper ID for vaulting\n Shopper(id = \"shopper-123\")\n },\n onSuccess = { result: DropInSubmitResult ->\n Log.d(\"Checkout\", \"Card payment successful!\")\n Log.d(\"Checkout\", \"System transaction ID: ${result.systemTransactionId}\")\n Log.d(\"Checkout\", \"Payment method: ${result.paymentMethod}\")\n \n // CRITICAL: Verify on backend\n verifyPaymentOnBackend(result)\n },\n onError = { error: BaseSdkException ->\n Log.e(\"Checkout\", \"Card payment failed\", error)\n Toast.makeText(\n context,\n \"Payment failed: ${error.message}\",\n Toast.LENGTH_LONG\n ).show()\n }\n )\n )\n checkoutDropInComponent = checkoutDropIn.create()\n }\n }\n \n // Render Drop-in\n if (isLoading) {\n CircularProgressIndicator()\n } else {\n checkoutDropInComponent?.Content(modifier = Modifier.fillMaxWidth())\n }\n}\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"session-configuration-backend","__idx":9},"children":["Session configuration (backend)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Enable cards in your session request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// BACKEND: Create a session with cards enabled\nconst sessionRequest = {\n merchant: \"MERCHANT-1\",\n site: \"SITE-1\",\n sessionTimeout: 120,\n merchantTransactionId: crypto.randomUUID(),\n transactionMethod: {\n intent: {\n card: \"Authorisation\" // or \"Purchase\"\n }\n },\n amounts: {\n currencyCode: \"GBP\",\n transactionValue: 99.99\n },\n allowedFundingTypes: {\n cards: {\n // Card configuration from the Unity Portal will be used\n // You can optionally specify allowed card brands here\n allowedCardBrands: [\"visa\", \"mastercard\", \"amex\"]\n }\n },\n allowTransaction: true,\n serviceType: \"CheckoutDropIn\"\n};\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-flows","__idx":10},"children":["Payment flows"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in supports two card payment flows, configured via the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["intent"]}," parameter:"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Confirm payment (authorisation)","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two-step payment: authorise now, capture later (within scheme-specific time windows)."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"import com.pxp.checkout.models.DropInTransactionData\nimport com.pxp.checkout.models.DropInTransactionIntentData\nimport com.pxp.checkout.models.EntryType\nimport com.pxp.checkout.models.IntentType\n\ntransactionData = DropInTransactionData(\n currency = \"GBP\",\n amount = 149.99,\n entryType = EntryType.Ecom,\n intent = DropInTransactionIntentData(\n card = IntentType.Authorisation // Confirm Payment flow\n ),\n merchant = \"Demo Store\",\n merchantTransactionId = { UUID.randomUUID().toString() },\n merchantTransactionDate = { Instant.now().toString() }\n)\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this flow for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Physical products (capture on shipment)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Inventory validation needed"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Final amount may change (shipping, taxes)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Complex order workflows"]}]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Pay now (purchase)","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Immediate, single-step payment where funds are captured right away."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"import com.pxp.checkout.models.DropInTransactionData\nimport com.pxp.checkout.models.DropInTransactionIntentData\nimport com.pxp.checkout.models.EntryType\nimport com.pxp.checkout.models.IntentType\n\ntransactionData = DropInTransactionData(\n currency = \"GBP\",\n amount = 99.99,\n entryType = EntryType.Ecom,\n intent = DropInTransactionIntentData(\n card = IntentType.Purchase // Pay Now flow\n ),\n merchant = \"Demo Store\",\n merchantTransactionId = { UUID.randomUUID().toString() },\n merchantTransactionDate = { Instant.now().toString() }\n)\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this flow for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Digital products"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Simple orders with immediate fulfillment"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Subscriptions"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Donations"]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-responses","__idx":11},"children":["Handling responses"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"card-callback-data","__idx":12},"children":["Card callback data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a card payment succeeds, your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," callback receives the same standard result as other payment methods:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"onSuccess = { result: DropInSubmitResult ->\n Log.d(\"Checkout\", \"Payment details:\")\n Log.d(\"Checkout\", \"- System transaction ID: ${result.systemTransactionId}\")\n Log.d(\"Checkout\", \"- Merchant transaction ID: ${result.merchantTransactionId}\")\n Log.d(\"Checkout\", \"- Payment method: ${result.paymentMethod}\") // \"Card\"\n \n // Note: Amount, currency, card details must be retrieved from backend\n // 3D Secure authentication data is handled internally\n}\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-handling","__idx":13},"children":["Error handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Handle card-specific errors:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"import com.pxp.checkout.exceptions.BaseSdkException\n\nonError = { error: BaseSdkException ->\n Log.e(\"Checkout\", \"Error code: ${error.code}\")\n Log.e(\"Checkout\", \"Error message: ${error.message}\")\n \n // Handle specific error types\n when {\n error.message?.contains(\"declined\", ignoreCase = true) == true -> {\n Toast.makeText(\n context,\n \"Card declined. Please try a different card.\",\n Toast.LENGTH_LONG\n ).show()\n }\n error.message?.contains(\"insufficient\", ignoreCase = true) == true -> {\n Toast.makeText(\n context,\n \"Insufficient funds. Please use a different card.\",\n Toast.LENGTH_LONG\n ).show()\n }\n error.message?.contains(\"expired\", ignoreCase = true) == true -> {\n Toast.makeText(\n context,\n \"Card expired. Please use a different card.\",\n Toast.LENGTH_LONG\n ).show()\n }\n error.message?.contains(\"invalid\", ignoreCase = true) == true -> {\n Toast.makeText(\n context,\n \"Invalid card details. Please check and try again.\",\n Toast.LENGTH_LONG\n ).show()\n }\n error.message?.contains(\"3DS\", ignoreCase = true) == true ||\n error.message?.contains(\"authentication\", ignoreCase = true) == true -> {\n Toast.makeText(\n context,\n \"Authentication failed. Please try again.\",\n Toast.LENGTH_LONG\n ).show()\n }\n else -> {\n Toast.makeText(\n context,\n \"Payment failed: ${error.message}\",\n Toast.LENGTH_LONG\n ).show()\n }\n }\n}\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"common-error-scenarios","__idx":14},"children":["Common error scenarios"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following table describes common card error scenarios:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Scenario"},"children":["Scenario"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"How to detect"},"children":["How to detect"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Recommended action"},"children":["Recommended action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Card declined"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"declined\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Suggest trying different card"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Insufficient funds"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"insufficient\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Suggest using different card or payment method"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Card expired"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"expired\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Request valid card details"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Invalid card"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"invalid\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Ask customer to check card details"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["3D Secure failed"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"3DS\" or \"authentication\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Suggest trying again or contacting bank"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Network error"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"network\" or \"timeout\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Retry payment after brief delay"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Card errors return descriptive messages rather than specific error code constants. Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," property for error details. For production apps, implement robust error handling with retry logic and user-friendly messaging."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"backend-verification","__idx":15},"children":["Backend verification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always verify card payments on your backend to ensure payment success before fulfilling orders:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"import com.pxp.checkout.checkoutdropin.types.DropInSubmitResult\n\nonSuccess = { result: DropInSubmitResult ->\n // Send to backend for verification\n coroutineScope.launch {\n try {\n val response = apiClient.post(\"/api/verify-payment\") {\n contentType(ContentType.Application.Json)\n setBody(mapOf(\n \"systemTransactionId\" to result.systemTransactionId,\n \"merchantTransactionId\" to result.merchantTransactionId\n ))\n }\n \n if (response.status.value == 200) {\n val verified = response.body()\n if (verified.success) {\n // Navigate to success screen\n navController.navigate(\"success?orderId=${verified.orderId}\")\n } else {\n Toast.makeText(\n context,\n \"Payment verification failed\",\n Toast.LENGTH_LONG\n ).show()\n }\n }\n } catch (e: Exception) {\n Log.e(\"Checkout\", \"Verification error\", e)\n Toast.makeText(\n context,\n \"Failed to verify payment\",\n Toast.LENGTH_LONG\n ).show()\n }\n }\n}\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"backend-verification-code","__idx":16},"children":["Backend verification code"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the following backend code to verify card transactions via the PXP API:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// BACKEND: Verify card payment\napp.post('/api/verify-payment', async (req, res) => {\n const { systemTransactionId, merchantTransactionId } = req.body;\n \n try {\n // Query the PXP API to get transaction details\n const txnPath = `api/v1/transactions/${systemTransactionId}`;\n const { authHeader, requestId } = createAuthHeader(\n txnPath,\n '',\n process.env.PXP_TOKEN_ID,\n process.env.PXP_TOKEN_VALUE\n );\n \n const transaction = await fetch(\n `https://api-services.pxp.io/${txnPath}`,\n {\n headers: {\n 'X-Client-Id': process.env.PXP_CLIENT_ID,\n 'X-Request-Id': requestId,\n 'Authorization': authHeader\n }\n }\n ).then(r => r.json());\n \n // Verify transaction state\n if (transaction.state !== 'Authorised' && transaction.state !== 'Captured') {\n return res.json({ success: false, error: 'Transaction not successful' });\n }\n \n // Verify merchant transaction ID matches\n if (transaction.merchantTransactionId !== merchantTransactionId) {\n return res.json({ success: false, error: 'Transaction ID mismatch' });\n }\n \n // Verify amount matches expected amount from your order records\n const order = await getOrderByMerchantTransactionId(merchantTransactionId);\n const txnAmount = transaction.amounts?.transactionValue || transaction.amount || 0;\n if (Math.abs(txnAmount - order.amount) > 0.01) {\n return res.json({ success: false, error: 'Amount mismatch' });\n }\n \n // Verify funding type is card\n const fundingType = transaction.fundingData?.fundingType || \n transaction.fundingType || \n 'Unknown';\n if (fundingType !== 'Card') {\n return res.json({ success: false, error: 'Invalid funding type' });\n }\n \n // Fulfill order\n const orderId = await fulfillOrder(transaction);\n \n return res.json({ success: true, orderId });\n \n } catch (error) {\n console.error('Verification error:', error);\n return res.json({ success: false, error: 'Verification failed' });\n }\n});\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"advanced-card-flows","__idx":17},"children":["Advanced card flows"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"card-vaulting-one-click-payment","__idx":18},"children":["Card vaulting (one-click payment)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Card vaulting allows returning customers to pay with one click by saving their card. When enabled, customers who have previously saved a card can skip entering card details entirely."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"how-it-works-1","__idx":19},"children":["How it works"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The customer pays with a card and agrees to save it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Unity vaults the card and returns a vault ID."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["On return visit, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," provides the shopper ID."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Drop-in enables one-click card payment (no fields)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The customer taps \"Pay with saved card\" and payment completes instantly."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"enable-card-vaulting","__idx":20},"children":["Enable card vaulting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Implement ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," to enable vaulting:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"import com.pxp.checkout.checkoutdropin.CheckoutDropIn\nimport com.pxp.checkout.checkoutdropin.types.CheckoutDropInConfig\nimport com.pxp.checkout.components.checkoutdropincomponent.CheckoutDropInComponent\nimport com.pxp.checkout.models.DropInTransactionData\nimport com.pxp.checkout.models.DropInTransactionIntentData\nimport com.pxp.checkout.models.Environment\nimport com.pxp.checkout.models.EntryType\nimport com.pxp.checkout.models.IntentType\nimport com.pxp.checkout.checkoutdropin.types.DropInSubmitResult\nimport com.pxp.checkout.exceptions.BaseSdkException\nimport com.pxp.checkout.services.models.transaction.Shopper\n\n@Composable\nfun CheckoutScreen() {\n val context = LocalContext.current\n var sessionData by remember { mutableStateOf(null) }\n var checkoutDropInComponent by remember { mutableStateOf(null) }\n \n // Fetch session from backend\n LaunchedEffect(Unit) {\n sessionData = fetchSessionFromBackend()\n }\n \n // Initialize Drop-in once session is loaded\n LaunchedEffect(sessionData) {\n sessionData?.let { session ->\n val checkoutDropIn = CheckoutDropIn.initialize(\n context = context,\n config = CheckoutDropInConfig(\n environment = Environment.TEST,\n session = session,\n ownerType = \"MerchantGroup\",\n ownerId = \"MERCHANT-1\",\n transactionData = DropInTransactionData(\n currency = \"GBP\",\n amount = 99.99,\n entryType = EntryType.Ecom,\n intent = DropInTransactionIntentData(\n card = IntentType.Purchase\n ),\n merchant = \"Demo Store\",\n merchantTransactionId = { UUID.randomUUID().toString() },\n merchantTransactionDate = { Instant.now().toString() }\n ),\n // REQUIRED: Provide shopper ID to enable card vaulting\n onGetShopper = {\n val user = getCurrentUser()\n Shopper(id = user.shopperId) // e.g., Shopper(id = \"shopper-123\")\n },\n onSuccess = { result: DropInSubmitResult ->\n verifyPaymentOnBackend(result)\n navController.navigate(\"success\")\n },\n onError = { error: BaseSdkException ->\n Log.e(\"Checkout\", \"Card payment failed\", error)\n Toast.makeText(\n context,\n \"Payment failed: ${error.message}\",\n Toast.LENGTH_LONG\n ).show()\n }\n )\n )\n checkoutDropInComponent = checkoutDropIn.create()\n }\n }\n \n // Render Drop-in\n checkoutDropInComponent?.Content(modifier = Modifier.fillMaxWidth())\n}\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," returns a shopper ID, the SDK automatically:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fetches saved cards from the PXP API."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enables one-click payment for vaulted cards."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Handles vault setup during the first payment."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"card-vaulting-configuration","__idx":21},"children":["Card vaulting configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Card vaulting is enabled by implementing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," and optionally controlling consent with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["methodConfig.global.onGetConsent"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"CheckoutDropInConfig(\n // ... other config\n onGetShopper = {\n val user = getCurrentUser()\n Shopper(id = user.shopperId) // Required for vaulting\n },\n methodConfig = DropInMethodConfig(\n global = DropInGlobalConfig(\n onGetConsent = { paymentMethod ->\n // Control consent checkbox for card vaulting\n paymentMethod == PaymentMethod.CARD\n }\n ),\n card = DropInCardConfig() // Empty marker\n )\n)\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3d-secure-authentication","__idx":22},"children":["3D Secure authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["3D Secure authentication is handled automatically by the drop-in. When a card requires 3D Secure, the drop-in:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Detects that 3D Secure is required from the payment response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Launches the native Android 3D Secure UI."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Guides the customer through authentication (OTP, biometric, etc.)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Processes the authenticated payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fires your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," callback on completion."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No additional code is required for 3D Secure authentication. The drop-in manages the entire flow automatically."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["3D Secure UI is rendered using native Android components and adapts to the authentication method required by the card issuer (OTP, biometric, challenge questions, etc.). The UI is fully PCI DSS Level 1 compliant."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"recurring-card-payments","__idx":23},"children":["Recurring card payments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For subscriptions and recurring charges, use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IntentType.Authorisation"]}," flow with card vaulting enabled:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"import com.pxp.checkout.models.DropInTransactionData\nimport com.pxp.checkout.models.DropInTransactionIntentData\nimport com.pxp.checkout.models.EntryType\nimport com.pxp.checkout.models.IntentType\n\ntransactionData = DropInTransactionData(\n currency = \"GBP\",\n amount = 9.99,\n entryType = EntryType.Ecom,\n intent = DropInTransactionIntentData(\n card = IntentType.Authorisation // Use Authorisation for recurring\n ),\n merchant = \"Demo Store\",\n merchantTransactionId = { UUID.randomUUID().toString() },\n merchantTransactionDate = { Instant.now().toString() }\n)\n","lang":"kotlin"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After the first payment, use the vaulted card token to process subsequent recurring payments via the PXP API without customer interaction."]}]},"headings":[{"value":"Cards","id":"cards","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Key benefits","id":"key-benefits","depth":3},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Configuration","id":"configuration","depth":2},{"value":"Configuration properties","id":"configuration-properties","depth":3},{"value":"Complete example","id":"complete-example","depth":3},{"value":"Card requirements","id":"card-requirements","depth":3},{"value":"Implementation","id":"implementation","depth":2},{"value":"Session configuration (backend)","id":"session-configuration-backend","depth":3},{"value":"Payment flows","id":"payment-flows","depth":3},{"value":"Handling responses","id":"handling-responses","depth":2},{"value":"Card callback data","id":"card-callback-data","depth":3},{"value":"Error handling","id":"error-handling","depth":3},{"value":"Common error scenarios","id":"common-error-scenarios","depth":4},{"value":"Backend verification","id":"backend-verification","depth":2},{"value":"Backend verification code","id":"backend-verification-code","depth":3},{"value":"Advanced card flows","id":"advanced-card-flows","depth":2},{"value":"Card vaulting (one-click payment)","id":"card-vaulting-one-click-payment","depth":3},{"value":"How it works","id":"how-it-works-1","depth":4},{"value":"Enable card vaulting","id":"enable-card-vaulting","depth":4},{"value":"Card vaulting configuration","id":"card-vaulting-configuration","depth":4},{"value":"3D Secure authentication","id":"3d-secure-authentication","depth":3},{"value":"Recurring card payments","id":"recurring-card-payments","depth":3}],"frontmatter":{"seo":{"title":"Cards"}},"lastModified":"2026-05-20T14:05:06.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/drop-in/android/cards","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}