{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading"]},"type":"markdown"},"seo":{"title":"Configuration","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":"configuration","__idx":0},"children":["Configuration"]},{"$$mdtype":"Tag","name":"SubHeading","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure Checkout Drop-in once with unified settings for all payment methods, callbacks, and transaction data."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkout Drop-in uses a single, unified configuration at initialisation. Instead of configuring individual payment components, you configure Drop-in once and it automatically handles all payment methods."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuration-structure","__idx":2},"children":["Configuration structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All configuration happens at initialisation via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropIn.initialize()"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import CheckoutDropIn from '@pxpio/web-components-sdk/src/checkoutDropIn/CheckoutDropIn';\nimport IntentType from '@pxpio/web-components-sdk/src/basePxpCheckout/types/IntentType';\n\nconst checkoutDropIn = CheckoutDropIn.initialize({\n  // REQUIRED\n  environment: 'test',\n  session: sessionData,\n  ownerId: 'YourMerchantId',\n  // ownerType is set to 'MerchantGroup' automatically by Checkout Drop-in\n  transactionData: {\n    currency: 'USD',\n    amount: 99.99,\n    entryType: 'Ecom',\n    intent: {\n      card: IntentType.Authorisation,\n      paypal: IntentType.Authorisation\n    },\n    merchantTransactionId: crypto.randomUUID(),\n    merchantTransactionDate: () => new Date().toISOString()\n  },\n  \n  // REQUIRED: Callbacks\n  onSuccess: (result) => { /* ... */ },\n  onError: (error) => { /* ... */ },\n  \n  // OPTIONAL: Callbacks\n  onGetShopper: () => Promise.resolve({ id: 'shopper-123' }),\n  onBeforeSubmit: async (before) => { /* return true to proceed */ },\n  onSubmit: (submit) => { /* ... */ },\n  analyticsEvent: (event) => { /* ... */ }\n});\n\n// Mount to page\ncheckoutDropIn.create('checkout-drop-in-container');\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"required-configuration","__idx":3},"children":["Required configuration"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"environment","__idx":4},"children":["Environment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Specifies which Unity environment to connect to:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"{\n  environment: 'test' // or 'live'\n}\n","lang":"typescript"},"children":[]},{"$$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":"Value"},"children":["Value"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'test'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Sandbox environment. Use this for development, testing, and staging."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'live'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Live environment. Use this for production deployments."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"session-data","__idx":5},"children":["Session data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Session data is retrieved from your backend and contains payment configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"// Backend endpoint\nconst sessionData = await fetch('/api/create-session')\n  .then(response => response.json());\n\n// Pass to Drop-in\n{\n  session: sessionData\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Session data includes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionId"]},": The unique session identifier"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hmacKey"]},": HMAC authentication key"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptionKey"]},": Encryption key"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedFundingTypes"]},": Which payment methods are enabled"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Session timeout and merchant identification"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For session creation details, see our ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/web/implementation"},"children":["implementation guide"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"owner-identification","__idx":6},"children":["Owner identification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Identifies who owns this transaction:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"{\n  ownerId: 'YourMerchantId',\n  // ownerType is optional; Checkout Drop-in sets it to 'MerchantGroup'\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"transaction-data","__idx":7},"children":["Transaction data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Defines the payment amount, currency, and intent:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import IntentType from '@pxpio/web-components-sdk/src/basePxpCheckout/types/IntentType';\n\n{\n  transactionData: {\n    currency: 'USD',                      // ISO 4217 currency code\n    amount: 99.99,                        // Transaction amount\n    entryType: 'Ecom',                    // Entry type (usually 'Ecom' for web)\n    intent: {\n      card: IntentType.Authorisation,     // Card payment intent\n      paypal: IntentType.Authorisation    // PayPal payment intent\n    },\n    merchantTransactionId: crypto.randomUUID(),              // Unique per transaction\n    merchantTransactionDate: () => new Date().toISOString()  // Current timestamp\n  }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"merchant-transaction-id","__idx":8},"children":["Merchant transaction ID"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your unique identifier for the transaction:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"merchantTransactionId: crypto.randomUUID()\n\n// Or use your own format\nmerchantTransactionId: `order-${orderId}`\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"optional-configuration","__idx":9},"children":["Optional configuration"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"unified-callbacks","__idx":10},"children":["Unified callbacks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in provides unified callbacks that work for all payment methods:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { BaseSubmitResult } from '@pxpio/web-components-sdk/src/checkoutDropIn/types/BaseSubmitResult';\nimport BaseSdkException from '@pxpio/web-components-sdk/src/types/sdkExceptions/BaseSdkException';\nimport PaymentMethod from '@pxpio/web-components-sdk/src/components/checkoutDropInComponents/types/PaymentMethod';\n\n{\n  // REQUIRED: Get shopper information\n  onGetShopper: () => {\n    return Promise.resolve({ id: 'shopper-123' });\n  },\n  \n  // REQUIRED: Called when payment succeeds\n  onSuccess: async (result: BaseSubmitResult) => {\n    console.log('Payment successful:', result.systemTransactionId);\n    // CRITICAL: Always verify on backend before fulfilling order\n    await verifyPaymentOnBackend(result);\n  },\n  \n  // REQUIRED: Called when payment fails\n  onError: (error: BaseSdkException) => {\n    console.error('Payment failed:', error.code, error.message);\n  },\n  \n  // OPTIONAL: Called before payment submission (can cancel)\n  onBeforeSubmit: async (paymentMethod: PaymentMethod) => {\n    console.log('Payment method:', paymentMethod);\n    // Return false to cancel payment\n    return true;\n  },\n  \n  // OPTIONAL: Called when payment starts processing\n  onSubmit: (paymentMethod: PaymentMethod) => {\n    console.log('Processing payment...');\n  }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For detailed callback documentation, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/web/implementation"},"children":["Implementation"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"analytics","__idx":11},"children":["Analytics"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Track payment flow events:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"{\n  analyticsEvent: (event) => {\n    console.log('Analytics:', event.eventName, event);\n    // Send to your analytics platform\n    sendToGA4(event);\n  }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For detailed analytics documentation, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/web/analytics"},"children":["Analytics"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"backend-driven-configuration","__idx":12},"children":["Backend-driven configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Many behaviours are configured on the backend (in the Unity Portal), rather than in frontend code:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-method-availability","__idx":13},"children":["Payment method availability"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Controlled via session data:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// Backend session creation\n{\n  \"allowedFundingTypes\": {\n    \"cards\": [\"visa\", \"mastercard\"],\n    \"cardSchemes\": [\"Visa\", \"Mastercard\"],\n    \"wallets\": {\n      \"paypal\": {\n        \"allowedFundingOptions\": [\"PAYPAL\"],\n        \"merchantId\": \"paypal-merchant-123\"\n      },\n      \"googlePay\": {\n        \"merchantId\": \"your-googlepay-merchant-id\",\n        \"gatewayMerchantId\": \"gateway-merchant-id\",\n        \"merchantName\": \"Your merchant name\"\n      },\n      \"applePay\": {\n        \"merchantId\": \"your-applepay-merchant-id\"\n      }\n    }\n  }\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in automatically shows only enabled payment methods."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"branding","__idx":14},"children":["Branding"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in fetches and applies your ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/drop-in/branding"},"children":["branding configuration"]}," from the Unity Portal."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3ds-requirements","__idx":15},"children":["3DS requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in respects the amount thresholds, risk assessment rules, and exemptions configured in the Unity Portal. For more information, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/3ds"},"children":["3DS section"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"recurring-payments","__idx":16},"children":["Recurring payments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configured in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"{\n  transactionData: {\n    // ... other transaction fields\n    recurring: {\n      frequencyInDays: 30,\n      frequencyExpiration: '2025-12-31'\n    }\n  }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"complete-configuration-examples","__idx":17},"children":["Complete configuration examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"minimal-configuration-most-common","__idx":18},"children":["Minimal configuration (most common)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import CheckoutDropIn from '@pxpio/web-components-sdk/src/checkoutDropIn/CheckoutDropIn';\nimport IntentType from '@pxpio/web-components-sdk/src/basePxpCheckout/types/IntentType';\n\n// Get session from backend\nconst sessionData = await fetch('/api/create-session', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' }\n}).then(response => response.json());\n\n// Initialise with minimal config\nconst checkoutDropIn = CheckoutDropIn.initialize({\n  environment: 'test',\n  session: sessionData,\n  ownerId: 'YourMerchantId',\n  ownerType: 'MerchantGroup',\n  transactionData: {\n    currency: 'USD',\n    amount: 99.99,\n    entryType: 'Ecom',\n    intent: {\n      card: IntentType.Authorisation,\n      paypal: IntentType.Authorisation\n    },\n    merchantTransactionId: crypto.randomUUID(),\n    merchantTransactionDate: () => new Date().toISOString()\n  },\n  onGetShopper: () => Promise.resolve({ id: 'shopper-123' }),\n  onSuccess: async (result) => {\n    await verifyPaymentOnBackend(result);\n  },\n  onError: (error) => {\n    alert(`Payment failed: ${error.message}`);\n  }\n});\n\n// Mount\ncheckoutDropIn.create('checkout-drop-in-container');\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"full-configuration-with-all-callbacks","__idx":19},"children":["Full configuration (with all callbacks)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import CheckoutDropIn from '@pxpio/web-components-sdk/src/checkoutDropIn/CheckoutDropIn';\nimport IntentType from '@pxpio/web-components-sdk/src/basePxpCheckout/types/IntentType';\nimport PaymentMethod from '@pxpio/web-components-sdk/src/components/checkoutDropInComponents/types/PaymentMethod';\nimport { BaseSubmitResult } from '@pxpio/web-components-sdk/src/checkoutDropIn/types/BaseSubmitResult';\nimport BaseSdkException from '@pxpio/web-components-sdk/src/types/sdkExceptions/BaseSdkException';\n\n// Get session from backend\nconst sessionData = await fetch('/api/create-session', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' }\n}).then(response => response.json());\n\n// Initialise with all callbacks\nconst checkoutDropIn = CheckoutDropIn.initialize({\n  // REQUIRED\n  environment: 'live',\n  session: sessionData,\n  ownerId: 'YourMerchantId',\n  ownerType: 'MerchantGroup',\n  transactionData: {\n    currency: 'USD',\n    amount: 149.99,\n    entryType: 'Ecom',\n    intent: {\n      card: IntentType.Authorisation,\n      paypal: IntentType.Purchase\n    },\n    merchantTransactionId: `order-${orderId}`,\n    merchantTransactionDate: () => new Date().toISOString()\n  },\n  \n  // CALLBACKS\n  onGetShopper: () => Promise.resolve({ id: 'shopper-123' }),\n  \n  onBeforeSubmit: async (paymentMethod: PaymentMethod) => {\n    console.log('Payment method selected:', paymentMethod);\n    \n    // Custom validation\n    const isValid = await validateOrder(orderId);\n    if (!isValid) {\n      alert('Order validation failed. Please review your order.');\n      return false; // Cancel payment\n    }\n    \n    // Check inventory\n    const inStock = await checkInventory(orderId);\n    if (!inStock) {\n      alert('Item is out of stock. Please update your cart.');\n      return false; // Cancel payment\n    }\n    \n    return true; // Proceed with payment\n  },\n  \n  onSubmit: (paymentMethod: PaymentMethod) => {\n    console.log('Payment processing started for:', paymentMethod);\n    // Show loading spinner\n    document.getElementById('loading-spinner').style.display = 'block';\n  },\n  \n  onSuccess: async (result: BaseSubmitResult) => {\n    console.log('Payment successful:', result.systemTransactionId);\n    \n    document.getElementById('loading-spinner').style.display = 'none';\n    \n    // CRITICAL: Verify on backend before fulfilling\n    try {\n      const verified = await fetch('/api/verify-payment', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({\n          systemTransactionId: result.systemTransactionId,\n          merchantTransactionId: result.merchantTransactionId,\n          orderId: orderId\n        })\n      }).then(r => r.json());\n      \n      if (verified.success) {\n        window.location.href = `/order-confirmation?orderId=${verified.orderId}`;\n      } else {\n        alert('Payment verification failed. Please contact support.');\n      }\n    } catch (error) {\n      console.error('Verification failed:', error);\n      alert('Unable to verify payment. Please contact support.');\n    }\n  },\n  \n  onError: (error: BaseSdkException) => {\n    console.error('Payment error:', error);\n    document.getElementById('loading-spinner').style.display = 'none';\n    \n    // Show user-friendly error message based on error code and message\n    let userMessage = `Payment failed: ${error.message}`;\n    \n    if (error.code === 'SDK1116' && error.message.toLowerCase().includes('declined')) {\n      userMessage = 'Card declined. Please try a different card.';\n    } else if (error.code === 'SDK1116' && error.message.toLowerCase().includes('insufficient funds')) {\n      userMessage = 'Insufficient funds.';\n    } else if (error.code === 'SDK1114') {\n      userMessage = 'Card verification failed.';\n    } else if (error.code === 'SDK0500') {\n      userMessage = 'Connection error. Check your internet.';\n    } else if (error.message.toLowerCase().includes('session') || \n               error.message.toLowerCase().includes('expired')) {\n      userMessage = 'Session expired. Please refresh.';\n    }\n    \n    document.getElementById('error-message').textContent = userMessage;\n    document.getElementById('error-message').style.display = 'block';\n  },\n  \n  analyticsEvent: (event) => {\n    // Send to Google Analytics\n    if (typeof gtag !== 'undefined') {\n      gtag('event', event.eventName, {\n        event_category: 'checkout',\n        ...event\n      });\n    }\n    \n    // Send to backend\n    fetch('/api/analytics', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify(event)\n    }).catch(console.error);\n  }\n});\n\n// Mount\ncheckoutDropIn.create('checkout-drop-in-container');\n","lang":"typescript"},"children":[]}]},"headings":[{"value":"Configuration","id":"configuration","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Configuration structure","id":"configuration-structure","depth":2},{"value":"Required configuration","id":"required-configuration","depth":2},{"value":"Environment","id":"environment","depth":3},{"value":"Session data","id":"session-data","depth":3},{"value":"Owner identification","id":"owner-identification","depth":3},{"value":"Transaction data","id":"transaction-data","depth":3},{"value":"Merchant transaction ID","id":"merchant-transaction-id","depth":4},{"value":"Optional configuration","id":"optional-configuration","depth":2},{"value":"Unified callbacks","id":"unified-callbacks","depth":3},{"value":"Analytics","id":"analytics","depth":3},{"value":"Backend-driven configuration","id":"backend-driven-configuration","depth":2},{"value":"Payment method availability","id":"payment-method-availability","depth":3},{"value":"Branding","id":"branding","depth":3},{"value":"3DS requirements","id":"3ds-requirements","depth":3},{"value":"Recurring payments","id":"recurring-payments","depth":3},{"value":"Complete configuration examples","id":"complete-configuration-examples","depth":2},{"value":"Minimal configuration (most common)","id":"minimal-configuration-most-common","depth":3},{"value":"Full configuration (with all callbacks)","id":"full-configuration-with-all-callbacks","depth":3}],"frontmatter":{"seo":{"title":"Configuration"}},"lastModified":"2026-05-20T12:46:49.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/drop-in/web/configuration","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}