{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading","br","details","admonition","tabs","tab"]},"type":"markdown"},"seo":{"title":"PayPal","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":"paypal","__idx":0},"children":["PayPal"]},{"$$mdtype":"Tag","name":"SubHeading","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Accept PayPal, Venmo, and Pay Later payments with automatic popup handling and one-click vaulting for returning customers."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["PayPal is automatically included in the drop-in when enabled in your session. The drop-in handles all PayPal setup, button rendering, popup windows, 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":["PayPal appears automatically in the drop-in when it's enabled in your session configuration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The drop-in handles all PayPal setup, so you don't need PayPal-specific code."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["PayPal uses 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":["Customers can pay using PayPal, Venmo, or Pay Later financing options."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Returning customers can use one-click payments when their PayPal account is saved."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Standard PayPal branding is included automatically, ensuring a familiar checkout experience."]}]},{"$$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 selects PayPal:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The customer clicks \"PayPal\" in the accordion. The PayPal popup opens."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The customer logs in to their PayPal account."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The customer approves the payment in the PayPal interface."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The popup closes automatically."]},{"$$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":["Configure PayPal-specific settings for the PayPal button, checkout flow, and shipping integration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configuration-properties","__idx":5},"children":["Configuration properties"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following properties are available for PayPal configuration:"]},{"$$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":["fundingSources"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["PaypalFundingSources[]"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Funding sources to display (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'paypal'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'paylater'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'venmo'"]},"). Falls back to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session.allowedFundingTypes.wallets.paypal.allowedFundingOptions"]}," if not specified"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enableOneClickPayment"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["boolean"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Enable one-click payment for returning PayPal users (requires vaulting)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["locale"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Locale for PayPal button (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'en_US'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'fr_FR'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'de_DE'"]},"). Format is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["language_COUNTRY"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payeeEmailAddress"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payee email address for the transaction"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentDescription"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Description of the payment displayed to the buyer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buyerCountry"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Buyer's country code (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'US'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'GB'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'FR'"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["consentComponent"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["boolean"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Show/hide consent checkbox for saving payment method. Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shippingPreference"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["ShippingPreference"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Shipping preference: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'GetFromFile'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'NoShipping'"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'SetProvidedAddress'"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shippingOption"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Selected shipping option ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["useBuiltInChangePreferredPaymentMethod"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["boolean"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use built-in change preferred payment method functionality"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onShippingAddressChange"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["(data, actions) => void"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Called when shipping address changes. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["actions.reject()"]}," to reject invalid addresses and update pricing dynamically"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onShippingOptionsChange"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["(data, actions) => void"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Called when shipping option changes. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["actions.reject()"]}," to reject specific shipping options"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"settings-used-from-global-configuration","__idx":6},"children":["Settings used from global configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["PayPal inherits the following settings from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["methodConfig.global"]},":"]},{"$$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":"40%","data-label":"Property"},"children":["Property "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"60%","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":["onGetConsent"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["(paymentMethod) => boolean"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Controls whether to show consent checkbox for PayPal (used for vaulting)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCancel"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["(paymentMethod, data) => void"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Called when user cancels PayPal payment (closes popup)"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"complete-example","__idx":7},"children":["Complete example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This example shows a full PayPal configuration with global callbacks, shipping integration, and all PayPal-specific options:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"methodConfig: {\n  // Global callbacks that apply to PayPal\n  global: {\n    // Control consent checkbox for PayPal\n    onGetConsent: (paymentMethod: PaymentMethod) => {\n      // Show consent checkbox for PayPal to save payment method\n      if (paymentMethod === PaymentMethod.Paypal) {\n        return true;\n      }\n      return false;\n    },\n    \n    // Handle PayPal cancellation\n    onCancel: (paymentMethod: PaymentMethod, data: any) => {\n      if (paymentMethod === PaymentMethod.Paypal) {\n        console.log('PayPal payment cancelled', data);\n        \n        // Track analytics\n        trackEvent('paypal_cancelled', {\n          timestamp: Date.now()\n        });\n        \n        // Update UI\n        showNotification('PayPal payment was cancelled. Please try again.');\n      }\n    }\n  },\n  \n  paypal: {\n    // Funding sources to display\n    fundingSources: ['paypal', 'paylater', 'venmo'],\n    \n    // Enable one-click payment for returning users\n    enableOneClickPayment: true,\n    \n    // Locale for PayPal button and checkout experience\n    locale: 'en_US',\n    \n    // Payee email address\n    payeeEmailAddress: 'merchant@example.com',\n    \n    // Payment description shown to buyer\n    paymentDescription: 'Purchase from Demo Store',\n    \n    // Buyer's country code\n    buyerCountry: 'US',\n    \n    // Show/hide consent checkbox for saving the payment method\n    consentComponent: true,\n    \n    // Shipping preference\n    shippingPreference: 'GetFromFile', // or 'NoShipping' or 'SetProvidedAddress'\n    \n    // Use built-in change preferred payment method\n    useBuiltInChangePreferredPaymentMethod: false,\n    \n    // Callback when shipping address changes\n    onShippingAddressChange: (data, actions) => {\n      console.log('New shipping address:', data.shippingAddress);\n      \n      // Validate address - reject addresses outside US\n      if (data.shippingAddress.countryCode !== 'US') {\n        return actions.reject(data.errors.COUNTRY_ERROR);\n      }\n    },\n    \n    // Callback when shipping option changes\n    onShippingOptionsChange: (data, actions) => {\n      console.log('Shipping option selected:', data.selectedShippingOption);\n      \n      // Optionally reject certain shipping options\n      if (data.selectedShippingOption.id === '2') {\n        return actions.reject(data.errors.METHOD_UNAVAILABLE);\n      }\n    }\n  }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"paypal-requirements","__idx":8},"children":["PayPal requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["PayPal requires the following to function correctly:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Browser compatibility"]},": PayPal works on all modern browsers (Chrome, Firefox, Safari, Edge)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Customer setup"]},": The customer must have a PayPal account (created during checkout if needed)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTPS"]},": Your website must be served over HTTPS."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Unity Portal configuration"]},": PayPal must be enabled and configured in the Unity Portal."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Entry type"]},": PayPal only supports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entryType: \"Ecom\""]},"."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One-click payments require the buyer to have previously authorised your merchant account. Authorisations must be captured within 29 days for PayPal (7 days for Venmo)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"implementation","__idx":9},"children":["Implementation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["PayPal works through the standard implementation, with no PayPal-specific code needed:"]},{"$$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 { 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 (with PayPal enabled)\nconst response = await fetch('/api/create-session', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' }\n});\n\nconst result = await response.json();\n\nif (!result.success || !result.data) {\n  console.error('Failed to create session:', result.error);\n  throw new Error('Session creation failed');\n}\n\nconst sessionData = result.data;\n\n// Initialise Drop-in\nconst checkoutDropIn = CheckoutDropIn.initialize({\n  environment: 'test',\n  session: sessionData, // Must include paypal in allowedFundingTypes\n  ownerId: 'MERCHANT-1',\n  ownerType: 'MerchantGroup',\n  transactionData: {\n    currency: 'USD',\n    amount: 99.99,\n    entryType: 'Ecom',\n    intent: {\n      card: IntentType.Authorisation,\n      paypal: IntentType.Purchase  // Choose Purchase or Authorisation\n    },\n    merchantTransactionId: crypto.randomUUID(),\n    merchantTransactionDate: () => new Date().toISOString()\n  },\n  onGetShopper: () => Promise.resolve({ id: 'shopper-123' }),\n  onSuccess: async (result: BaseSubmitResult) => {\n    console.log('PayPal payment successful!');\n    console.log('System transaction ID:', result.systemTransactionId);\n    console.log('Payment method:', result.paymentMethod); // Will be \"Paypal\"\n    \n    // CRITICAL: Verify on backend\n    await verifyPaymentOnBackend(result);\n  },\n  onError: (error: BaseSdkException) => {\n    console.error('PayPal payment failed:', error);\n    alert(`Payment failed: ${error.message}`);\n  }\n});\n\n// Mount Drop-in\ncheckoutDropIn.create('checkout-drop-in-container');\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"session-configuration-backend","__idx":10},"children":["Session configuration (backend)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Enable PayPal in your session request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// BACKEND: Create a session with PayPal enabled\nconst sessionRequest = {\n  merchant: \"MERCHANT-1\",\n  site: \"SITE-1\",\n  sessionTimeout: 120,\n  merchantTransactionId: crypto.randomUUID(),\n  transactionMethod: {\n    intent: {\n      paypal: \"Purchase\"  // or \"Authorisation\"\n    }\n  },\n  amounts: {\n    currencyCode: \"USD\",\n    transactionValue: 99.99\n  },\n  allowedFundingTypes: {\n    wallets: {\n      paypal: {\n        // PayPal configuration from the Unity Portal will be used\n        // You can optionally specify allowedFundingOptions here\n        allowedFundingOptions: [\"paypal\", \"paylater\", \"venmo\"]\n      }\n    }\n  },\n  allowTransaction: true,\n  serviceType: \"CheckoutDropIn\"\n};\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-flows","__idx":11},"children":["Payment flows"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in supports two PayPal 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":"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":"typescript","header":{"controls":{"copy":{}}},"source":"import IntentType from '@pxpio/web-components-sdk/src/basePxpCheckout/types/IntentType';\n\ntransactionData: {\n  currency: 'USD',\n  amount: 99.99,\n  entryType: 'Ecom',\n  intent: {\n    card: IntentType.Authorisation,\n    paypal: IntentType.Purchase  // Pay Now flow\n  },\n  merchantTransactionId: crypto.randomUUID(),\n  merchantTransactionDate: () => new Date().toISOString()\n}\n","lang":"typescript"},"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":"div","attributes":{"label":"Confirm payment (Authorisation)","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two-step payment: authorise now, capture later (within 29 days for PayPal, 7 days for Venmo)."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import IntentType from '@pxpio/web-components-sdk/src/basePxpCheckout/types/IntentType';\n\ntransactionData: {\n  currency: 'USD',\n  amount: 149.99,\n  entryType: 'Ecom',\n  intent: {\n    card: IntentType.Authorisation,\n    paypal: IntentType.Authorisation  // Confirm Payment flow\n  },\n  merchantTransactionId: crypto.randomUUID(),\n  merchantTransactionDate: () => new Date().toISOString()\n}\n","lang":"typescript"},"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":"Heading","attributes":{"level":2,"id":"handling-responses","__idx":12},"children":["Handling responses"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"paypal-callback-data","__idx":13},"children":["PayPal callback data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a PayPal 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":"typescript","header":{"controls":{"copy":{}}},"source":"onSuccess: (result: BaseSubmitResult) => {\n  console.log('Payment details:');\n  console.log('- System transaction ID:', result.systemTransactionId);\n  console.log('- Merchant transaction ID:', result.merchantTransactionId);\n  console.log('- Payment method:', result.paymentMethod); // \"Paypal\"\n  \n  // Note: Amount, currency, and other transaction details must be retrieved from backend\n  // PayPal authentication is handled internally by PayPal\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-handling","__idx":14},"children":["Error handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Handle PayPal-specific errors:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import BaseSdkException from '@pxpio/web-components-sdk/src/types/sdkExceptions/BaseSdkException';\n\nonError: (error: BaseSdkException) => {\n  console.error('Error code:', error.code);\n  console.error('Error message:', error.message);\n  \n  // Handle user cancellation\n  if (error.message.includes('cancelled') || error.message.includes('closed')) {\n    console.log('User cancelled PayPal payment');\n    // Don't show error - user intentionally cancelled\n    return;\n  }\n  \n  // Handle PayPal-specific errors based on message content\n  if (error.message.includes('insufficient funds')) {\n    alert('Insufficient funds in PayPal account. Please add funds or use a different payment method.');\n  } else if (error.message.includes('restricted')) {\n    alert('Your PayPal account is restricted. Please contact PayPal support.');\n  } else if (error.message.includes('declined')) {\n    alert('Payment declined by PayPal. Please try a different payment method.');\n  } else {\n    alert(`PayPal payment failed: ${error.message}`);\n  }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"common-error-scenarios","__idx":15},"children":["Common error scenarios"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following table describes common PayPal 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":["User cancelled"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"cancelled\" or \"closed\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No alert needed - user action was intentional"]}]},{"$$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 adding funds or using different payment method"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Account restricted"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," contains \"restricted\""]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Direct user to contact PayPal support"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Payment 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 payment method"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["PayPal errors return descriptive messages rather than specific error code constants. Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," property for error details. You can also use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCancel"]}," callback in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["methodConfig.global"]}," to specifically handle user cancellations."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"backend-verification","__idx":16},"children":["Backend verification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always verify PayPal payments on your backend to ensure payment success before fulfilling orders:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { BaseSubmitResult } from '@pxpio/web-components-sdk/src/checkoutDropIn/types/BaseSubmitResult';\n\nonSuccess: async (result: BaseSubmitResult) => {\n  // Send to backend for verification\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    })\n  }).then(r => r.json());\n  \n  if (verified.success) {\n    window.location.href = `/success?orderId=${verified.orderId}`;\n  } else {\n    alert('Payment verification failed');\n  }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"backend-verification-code","__idx":17},"children":["Backend verification code"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the following backend code to verify PayPal transactions via the PXP API:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// BACKEND: Verify PayPal 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    // PayPal payments show as PayPal funding type\n    const fundingType = transaction.fundingData?.fundingType || \n                       transaction.fundingType || \n                       'Unknown';\n    if (fundingType !== 'PayPal') {\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-paypal-flows","__idx":18},"children":["Advanced PayPal flows"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"paypal-vaulting-one-click-payment","__idx":19},"children":["PayPal vaulting (one-click payment)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["PayPal vaulting allows returning customers to pay with one click by saving their PayPal account. When enabled, customers who have previously connected their PayPal account can skip the PayPal login flow entirely."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"how-it-works-1","__idx":20},"children":["How it works"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The customer pays with PayPal and agrees to save their account."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["PayPal vaults the account 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 PayPal payment (no popup)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The customer clicks \"Pay with PayPal\" and payment completes instantly."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"enable-paypal-vaulting","__idx":21},"children":["Enable PayPal 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":"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 { 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 (with PayPal enabled)\nconst response = await fetch('/api/create-session', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' }\n});\n\nconst result = await response.json();\n\nif (!result.success || !result.data) {\n  console.error('Failed to create session:', result.error);\n  throw new Error('Session creation failed');\n}\n\nconst sessionData = result.data;\n\nconst checkoutDropIn = CheckoutDropIn.initialize({\n  environment: 'test',\n  session: sessionData,\n  ownerId: 'MERCHANT-1',\n  ownerType: 'MerchantGroup',\n  transactionData: {\n    currency: 'USD',\n    amount: 99.99,\n    entryType: 'Ecom',\n    intent: {\n      card: IntentType.Purchase,\n      paypal: IntentType.Purchase\n    },\n    merchantTransactionId: crypto.randomUUID(),\n    merchantTransactionDate: () => new Date().toISOString()\n  },\n  // REQUIRED: Provide shopper ID to enable PayPal vaulting\n  onGetShopper: async () => {\n    const user = await getCurrentUser();\n    return { id: user.shopperId }; // e.g., { id: 'shopper-123' }\n  },\n  onSuccess: async (result: BaseSubmitResult) => {\n    await verifyPaymentOnBackend(result);\n    window.location.href = '/success';\n  },\n  onError: (error: BaseSdkException) => {\n    console.error('PayPal payment failed:', error);\n    alert(`Payment failed: ${error.message}`);\n  }\n});\n\ncheckoutDropIn.create('checkout-drop-in-container');\n","lang":"typescript"},"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 the PayPal user ID token from the PXP API."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enables one-click payment for vaulted PayPal accounts."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Handles vault setup during the first payment."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"paypal-vaulting-configuration","__idx":22},"children":["PayPal vaulting configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can configure PayPal vaulting behaviour using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["methodConfig.paypal.enableOneClickPayment"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"CheckoutDropIn.initialize({\n  // ... other config\n  methodConfig: {\n    paypal: {\n      enableOneClickPayment: true  // Enable PayPal vaulting\n    }\n  }\n});\n","lang":"typescript"},"children":[]}]},"headings":[{"value":"PayPal","id":"paypal","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":"Settings used from global configuration","id":"settings-used-from-global-configuration","depth":3},{"value":"Complete example","id":"complete-example","depth":3},{"value":"PayPal requirements","id":"paypal-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":"PayPal callback data","id":"paypal-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 PayPal flows","id":"advanced-paypal-flows","depth":2},{"value":"PayPal vaulting (one-click payment)","id":"paypal-vaulting-one-click-payment","depth":3},{"value":"How it works","id":"how-it-works-1","depth":4},{"value":"Enable PayPal vaulting","id":"enable-paypal-vaulting","depth":4},{"value":"PayPal vaulting configuration","id":"paypal-vaulting-configuration","depth":4}],"frontmatter":{"seo":{"title":"PayPal"}},"lastModified":"2026-05-06T10:44:47.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/drop-in/web/paypal","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}