{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading","br","details","required","admonition"]},"type":"markdown"},"seo":{"title":"Events","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"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"events","__idx":0},"children":["Events"]},{"$$mdtype":"Tag","name":"SubHeading","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Implement callbacks to customise your Payout Drop-in withdrawal flow."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payout Drop-in provides a unified event system across payout methods. Use these callbacks to inject business logic and UX customisations at critical points in the withdrawal flow. The SDK loads instruments and submits payouts; you control confirmation, loading states, error messaging, and backend reconciliation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Callbacks enable you to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Supply the authenticated shopper ID used to load stored instruments and PayPal."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validate business rules before a card-on-file payout proceeds."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Display custom loading states and progress indicators."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Show shopper-safe error messages."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify successful submissions on your backend before updating withdrawal status."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Track analytics and monitor withdrawal performance."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Offer retry or alternative methods when errors occur."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," are required. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," is strongly recommended whenever Drop-in must resolve stored instruments. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBeforeSubmit"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmit"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["analyticsEvent"]}," are optional."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["PayPal uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," for the submit path. Drive PayPal loading UI from those callbacks. There is no Drop-in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCancel"]}," for the PayPal stored panel. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBeforeSubmit"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmit"]}," run for Card, Apple Pay, and Google Pay only. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPayoutMethodChange"]}," isn't available on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutDropIn.initialize()"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some failures occur outside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},", such as synchronous validation from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initialize()"]},", or a rejected ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," promise that causes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," to reject. Wrap ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initialize()"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["try"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["catch"]},". When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," runs during ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1700"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1701"]},"), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," usually settles without throwing. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/web/error-handling"},"children":["Error handling"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"supported-events","__idx":2},"children":["Supported events"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"ongetshopper","__idx":3},"children":["onGetShopper"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This callback provides shopper information so Drop-in can load stored payout instruments and the PayPal wallet association."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Typical uses include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Provide the shopper ID for logged-in users."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enable Card, Apple Pay, and Google Pay token lists for returning shoppers."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Resolve the linked PayPal account for the PayPal panel."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reject guest or unauthenticated sessions before Drop-in mounts."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"event-data","__idx":4},"children":["Event data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This callback receives no parameters and must return a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Promise"]}," that resolves to a shopper object."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"return-value","__idx":5},"children":["Return value"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The callback must resolve to a shopper object with this property:"]},{"$$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":{"data-label":"Property"},"children":["Property"]},{"$$mdtype":"Tag","name":"th","attributes":{"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":["id"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The stable shopper identifier from your authenticated session. Don't take this from untrusted client input alone."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example-implementation","__idx":6},"children":["Example implementation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example returns the authenticated shopper ID from your session API:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const payoutDropIn = PayoutDropIn.initialize({\n  // ... other config\n  onGetShopper: async () => {\n    const session = await fetch('/api/me').then((response) => response.json());\n\n    if (!session.shopperId) {\n      throw new Error('Shopper not authenticated');\n    }\n\n    return { id: session.shopperId };\n  },\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Require login before withdrawals:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"onGetShopper: async () => {\n  const user = getAuthenticatedUser();\n\n  if (!user?.shopperId) {\n    throw new Error('Log in to withdraw funds');\n  }\n\n  return { id: user.shopperId };\n},\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Without a shopper ID, token retrieval is skipped and PayPal can't resolve a linked account. Methods may disappear rather than throwing. If this promise rejects, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," rejects. Show a login prompt and don't assume ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," will fire."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"onbeforesubmit","__idx":7},"children":["onBeforeSubmit"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in calls this callback for Card, Apple Pay, and Google Pay when the shopper is about to submit a withdrawal. This is your last chance to validate data or cancel before card-on-file submit starts."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this callback to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Perform final validation before payout submission."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify withdrawal eligibility or account status."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Display confirmation dialogs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Track analytics events."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Block duplicate withdrawals while one is already in flight."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"event-data-1","__idx":8},"children":["Event data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The callback receives the selected payout method:"]},{"$$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":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"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":["payoutMethod"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["PayoutMethod"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The selected payout method for the panel that is submitting. One of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Card"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ApplePay"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GooglePay"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"return-value-1","__idx":9},"children":["Return value"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The return value controls whether submission continues:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["undefined"]},": Continue with payout submission. If the callback returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["undefined"]},", Drop-in treats that as continue."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},": Cancel payout submission. Loading state is cleared; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmit"]}," isn't called."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Promise<boolean>"]},": Async validation (the resolved value determines whether to proceed)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example-implementation-1","__idx":10},"children":["Example implementation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example confirms the withdrawal and checks eligibility before allowing submit:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { PayoutDropIn } from '@pxpio/web-components-sdk';\n\nconst payoutDropIn = PayoutDropIn.initialize({\n  // ... other config\n  onBeforeSubmit: async (payoutMethod) => {\n    console.log('Payout method selected:', payoutMethod);\n\n    const confirmed = await showConfirmationDialog({\n      title: 'Confirm withdrawal',\n      message: `Withdraw ${formatMoney(amount)} using ${payoutMethod}?`,\n      confirmText: 'Confirm',\n      cancelText: 'Cancel',\n    });\n\n    if (!confirmed) {\n      return false;\n    }\n\n    const check = await fetch('/api/withdrawal/eligibility', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({\n        withdrawalId,\n        payoutMethod,\n      }),\n    }).then((response) => response.json());\n\n    if (!check.eligible) {\n      showMessage(check.reason);\n      return false;\n    }\n\n    return true;\n  },\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This shorter example cancels submit with a synchronous eligibility check:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"onBeforeSubmit: (payoutMethod) => {\n  if (!isWithdrawalAllowed(payoutMethod)) {\n    showMessage(\"This withdrawal can't proceed. Please review your details.\");\n    return false;\n  }\n\n  return true;\n},\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returning ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," only allows the SDK to continue. It isn't server authorisation of the payout. Perform final reconciliation on your backend after ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," or a webhook."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"onsubmit","__idx":11},"children":["onSubmit"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in calls this callback for Card, Apple Pay, and Google Pay when payout processing begins, after ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBeforeSubmit"]}," validation passes. Use this to show loading indicators and disable UI elements."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common patterns include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Show loading spinners or progress indicators."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Disable submit controls to prevent double-submission."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Display \"Processing withdrawal…\" messages."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update UI to show the payout is in progress."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Track analytics for payout submission."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"event-data-2","__idx":12},"children":["Event data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The callback receives the payout method that started submission:"]},{"$$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":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"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":["payoutMethod"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["PayoutMethod"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The payout method whose submission has started (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Card"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ApplePay"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GooglePay"]},")."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example-implementation-2","__idx":13},"children":["Example implementation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example shows a loading overlay and disables the withdrawal form:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const payoutDropIn = PayoutDropIn.initialize({\n  // ... other config\n  onSubmit: (payoutMethod) => {\n    console.log('Processing payout with:', payoutMethod);\n\n    const overlay = document.getElementById('payout-overlay');\n    if (overlay) {\n      overlay.hidden = false;\n    }\n\n    disableWithdrawalForm(true);\n  },\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example shows loading UI and warns if submit takes longer than expected:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"let loadingTimeout: ReturnType<typeof setTimeout> | undefined;\n\nonSubmit: (payoutMethod) => {\n  setLoadingState(true);\n\n  loadingTimeout = setTimeout(() => {\n    showMessage(\n      'This withdrawal is taking longer than expected. Please wait…'\n    );\n  }, 10000);\n\n  window.payoutStartTime = Date.now();\n},\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pair with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," to clear loading state. Drop-in also clears its own submission-in-progress flag when those outcomes are delivered through the SDK handler."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"onsuccess","__idx":14},"children":["onSuccess"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in calls this callback after a payout submission succeeds. It receives the result from the payout processing path, including PayPal."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After a successful submit, you typically:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify the payout on your backend (required)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Redirect to a status page after verification."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Display success messages."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Track successful payout analytics."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Clear loading UI."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"event-data-3","__idx":15},"children":["Event data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The callback receives a result object with these properties:"]},{"$$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":{"data-label":"Event data"},"children":["Event data"]},{"$$mdtype":"Tag","name":"th","attributes":{"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":["result"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["PayoutDropInSubmitResult"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The payout processing result from the SDK."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result.systemTransactionId"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string | undefined"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Unity system transaction ID for a single-method payout. Prefer this for backend verification when present."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result.merchantTransactionId"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string | undefined"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your merchant transaction ID when returned by the flow."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result.payoutMethod"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["PayoutMethod | undefined"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The method used for a single-method payout (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Card"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Paypal"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ApplePay"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GooglePay"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result.payouts"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["ClosedLoopPayoutResult[] | undefined"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Closed-loop results when that flow creates one or more payout transactions. Each entry has ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["systemTransactionId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]},". When a line isn't ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorised"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Pending"]},", it can also include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorReason"]},". For closed-loop, top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["systemTransactionId"]}," may be omitted."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutDropInSubmitResult"]}," type:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"interface PayoutDropInSubmitResult {\n  systemTransactionId?: string;\n  merchantTransactionId?: string;\n  payoutMethod?: PayoutMethod;\n  payouts?: Array<{\n    systemTransactionId: string;\n    merchantTransactionId: string;\n    amount?: number;\n    currency?: string;\n    errorCode?: string;\n    errorReason?: string;\n  }>;\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," callback is a frontend event and can be manipulated in the browser. For closed-loop, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," can fire with a mix of successful and failed lines in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payouts"]},". Never mark a withdrawal paid, credit a balance, or settle funds based on this callback alone. Always verify with your webhook handler or a server-side transaction lookup before updating withdrawal status."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example-implementation-3","__idx":16},"children":["Example implementation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example verifies the payout on your backend, then redirects to a status page:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import {\n  PayoutDropIn,\n  type PayoutDropInSubmitResult,\n} from '@pxpio/web-components-sdk';\n\nconst payoutDropIn = PayoutDropIn.initialize({\n  // ... other config\n  onSuccess: async (result: PayoutDropInSubmitResult) => {\n    if (loadingTimeout) {\n      clearTimeout(loadingTimeout);\n    }\n\n    setLoadingState(false);\n    showMessage('Withdrawal received. Verifying…');\n\n    try {\n      const verification = await fetch('/api/verify-payout', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({\n          systemTransactionId: result.systemTransactionId,\n          merchantTransactionId: result.merchantTransactionId,\n          payoutMethod: result.payoutMethod,\n          payouts: result.payouts,\n        }),\n      }).then((response) => {\n        if (!response.ok) {\n          throw new Error('Verification request failed');\n        }\n        return response.json();\n      });\n\n      if (verification.success) {\n        window.location.href = `/withdrawals/${verification.id}/status`;\n        return;\n      }\n\n      showMessage(\n        \"We couldn't verify this withdrawal yet. Please check your email or contact support with your reference: \" +\n          `${result.merchantTransactionId ?? result.systemTransactionId}`\n      );\n    } catch (error) {\n      console.error('Failed to verify payout:', error);\n      showMessage(\n        \"Unable to verify this withdrawal. It may still be processing. Contact support with your reference: \" +\n          `${result.merchantTransactionId ?? result.systemTransactionId}`\n      );\n    }\n  },\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"onerror","__idx":17},"children":["onError"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in calls this callback when an error occurs during configuration, method resolution, or payout submission."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Handle errors so you can:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Display shopper-safe error messages."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log errors for debugging and monitoring."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Track failed payout analytics."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Offer retry or alternative methods."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Hide loading indicators."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Re-enable form controls."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"event-data-4","__idx":18},"children":["Event data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The callback receives a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BaseSdkException"]}," with these properties:"]},{"$$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":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"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":["error"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["BaseSdkException"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The error object containing details about what went wrong."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A human-readable error message. Derive shopper copy carefully; prefer your own mapped messages."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.ErrorCode"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The SDK error code in the form ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK####"]}," (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'SDK1700'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'SDK1701'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'SDK1703'"]},"). Use this for programmatic handling."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.name"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The exception class name."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.details"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["unknown"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A structured payload on some payout initiation failures."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Import from:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import type { BaseSdkException } from '@pxpio/web-components-sdk';\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.ErrorCode"]}," for branching. There's no separate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," property on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BaseSdkException"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"common-error-scenarios","__idx":19},"children":["Common error scenarios"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following table shows common error scenarios and how to detect and respond to them:"]},{"$$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":{"data-label":"Scenario"},"children":["Scenario"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Detection approach"},"children":["Detection approach"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"User action"},"children":["User action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payout Drop-in configuration missing"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.ErrorCode === 'SDK1700'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Refresh or try again later. Confirm the site service is active."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No eligible payout methods"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.ErrorCode === 'SDK1701'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Link an eligible instrument or use another account path."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payout initiation or card-on-file submit failed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.ErrorCode === 'SDK1703'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry or choose another method. Confirm backend transaction state first."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Network error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.ErrorCode === 'SDK0500'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check the connection and retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Session or credential problem"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}," mentions session or credentials"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Refresh the page and create a new payout session."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/web/error-handling"},"children":["Error handling"]}," for the full code table, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1703"]}," collision notes, and recovery patterns."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example-implementation-4","__idx":20},"children":["Example implementation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example clears loading state and maps common payout error codes to shopper-safe messages:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import {\n  PayoutDropIn,\n  type BaseSdkException,\n} from '@pxpio/web-components-sdk';\n\nconst payoutDropIn = PayoutDropIn.initialize({\n  // ... other config\n  onError: (error: BaseSdkException) => {\n    if (loadingTimeout) {\n      clearTimeout(loadingTimeout);\n    }\n\n    setLoadingState(false);\n    disableWithdrawalForm(false);\n\n    console.error('Payout Drop-in', {\n      errorCode: error.ErrorCode,\n      message: error.message,\n      name: error.name,\n      details: error.details,\n    });\n\n    let userMessage =\n      \"We couldn't complete your withdrawal. Please try again or contact support.\";\n\n    if (error.ErrorCode === 'SDK0500') {\n      userMessage =\n        'Network connection issue. Please check your internet connection and try again.';\n    } else if (error.ErrorCode === 'SDK1700') {\n      userMessage =\n        \"We couldn't load withdrawal settings. Please refresh or try again later.\";\n    } else if (error.ErrorCode === 'SDK1701') {\n      userMessage = 'No withdrawal methods are available for your account.';\n    } else if (error.ErrorCode === 'SDK1703') {\n      userMessage =\n        \"This withdrawal couldn't be completed. Please try again or choose another method.\";\n    }\n\n    showMessage(userMessage);\n  },\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"analyticsevent","__idx":21},"children":["analyticsEvent"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Optional hook for structured SDK analytics payloads. Treat it as observational alongside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},", and backend webhooks."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example-implementation-5","__idx":22},"children":["Example implementation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example forwards SDK analytics events to Google Analytics when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["gtag"]}," is available:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"analyticsEvent: (event) => {\n  if (typeof gtag !== 'undefined') {\n    gtag('event', event.eventName, {\n      session_id: event.sessionId,\n      timestamp:\n        event.timestamp instanceof Date\n          ? event.timestamp.toISOString()\n          : event.timestamp,\n    });\n  }\n},\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't block the withdrawal UI waiting on analytics network calls. Fire and forget, or queue events. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/web/analytics"},"children":["Analytics"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"event-data-structures","__idx":23},"children":["Event data structures"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payoutmethod","__idx":24},"children":["PayoutMethod"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For Payout Drop-in on Web, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutMethod"]}," identifies the method in use. Values for Card, PayPal, Apple Pay, and Google Pay are:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"enum PayoutMethod {\n  Card = 'Card',\n  Paypal = 'Paypal',\n  ApplePay = 'ApplePay',\n  GooglePay = 'GooglePay',\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Import from:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { PayoutMethod } from '@pxpio/web-components-sdk';\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payoutdropinsubmitresult-interface","__idx":25},"children":["PayoutDropInSubmitResult interface"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The success callback receives a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutDropInSubmitResult"]}," object:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"interface PayoutDropInSubmitResult {\n  systemTransactionId?: string;\n  merchantTransactionId?: string;\n  payoutMethod?: PayoutMethod;\n  payouts?: Array<{\n    systemTransactionId: string;\n    merchantTransactionId: string;\n  }>;\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Import from:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import type { PayoutDropInSubmitResult } from '@pxpio/web-components-sdk';\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"basesdkexception-interface","__idx":26},"children":["BaseSdkException interface"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The error callback receives a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BaseSdkException"]}," object:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"interface BaseSdkException {\n  message: string;\n  ErrorCode: string;\n  name?: string;\n  details?: unknown;\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Import from:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import type { BaseSdkException } from '@pxpio/web-components-sdk';\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"shopper-interface","__idx":27},"children":["Shopper interface"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," callback must return a shopper object:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"interface Shopper {\n  id: string;\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling-in-events","__idx":28},"children":["Error handling in events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Handle event-callback errors gracefully and give shoppers clear next steps. Prefer branching on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ErrorCode"]},", then fall back to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}," when you need more context."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"onError: (error: BaseSdkException) => {\n  hideLoadingIndicator();\n\n  if (error.ErrorCode === 'SDK1701') {\n    showMessage('No withdrawal methods are available for your account.');\n    return;\n  }\n\n  if (error.ErrorCode === 'SDK1700') {\n    showMessage(\n      \"We couldn't load withdrawal settings. Please refresh or try again later.\"\n    );\n    return;\n  }\n\n  if (error.ErrorCode === 'SDK1703') {\n    showMessage(\n      \"This withdrawal couldn't be completed. Please try again or choose another method.\"\n    );\n    return;\n  }\n\n  showMessage(\n    \"We couldn't complete your withdrawal. Please try again or contact support.\"\n  );\n},\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For recovery patterns, retry guidance, and the full code reference, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/web/error-handling"},"children":["Error handling"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"callback-execution-order","__idx":29},"children":["Callback execution order"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Understanding the callback flow helps you implement withdrawal handling correctly."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"card-apple-pay-and-google-pay","__idx":30},"children":["Card, Apple Pay, and Google Pay"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Callbacks run in this order for card-on-file methods:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]},": Runs at the start of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]},". Returns the shopper ID used for token lookup."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBeforeSubmit"]},": Shopper selects a stored token and confirms. Return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["undefined"]}," to proceed, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," to cancel."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmit"]},": Runs if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBeforeSubmit"]}," allows submission. Show loading UI."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},": Submission completed or failed. Verify on your backend after ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"paypal","__idx":31},"children":["PayPal"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Callbacks run in this order for the PayPal panel:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]},": Runs at the start of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]},". Returns the shopper ID used for wallet association lookup."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},": Shopper submits from the PayPal panel. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBeforeSubmit"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmit"]}," aren't called for this panel."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"mount-failures","__idx":32},"children":["Mount failures"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["During mount, failures can surface like this:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]},": Runs at the start of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configuration or empty-method failures during mount call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1700"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1701"]},", and related codes). ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," usually settles without throwing in those cases."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A rejected ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," causes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," to reject instead of calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"complete-integration-example","__idx":33},"children":["Complete integration example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example wires the main callbacks together for a Payout Drop-in mount:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import {\n  PayoutDropIn,\n  type PayoutDropInSubmitResult,\n  type BaseSdkException,\n} from '@pxpio/web-components-sdk';\n\nlet loadingTimeout: ReturnType<typeof setTimeout> | undefined;\n\nasync function initializePayoutDropIn(sessionData: unknown) {\n  const payoutDropIn = PayoutDropIn.initialize({\n    environment: 'test',\n    session: sessionData,\n    ownerId: 'YOUR-MERCHANT-GROUP-ID',\n    transactionData: {\n      currency: 'USD',\n      amount: 25,\n      entryType: 'Ecom',\n      merchantTransactionId: crypto.randomUUID(),\n      merchantTransactionDate: () => new Date().toISOString(),\n    },\n\n    onGetShopper: async () => {\n      const user = getAuthenticatedUser();\n      if (!user?.shopperId) {\n        throw new Error('Log in to withdraw funds');\n      }\n      return { id: user.shopperId };\n    },\n\n    onBeforeSubmit: async (payoutMethod) => {\n      const confirmed = await showConfirmationDialog({\n        title: 'Confirm withdrawal',\n        message: `Withdraw using ${payoutMethod}?`,\n        confirmText: 'Confirm',\n        cancelText: 'Cancel',\n      });\n      return confirmed;\n    },\n\n    onSubmit: (payoutMethod) => {\n      console.log('Processing payout:', payoutMethod);\n      setLoadingState(true);\n      loadingTimeout = setTimeout(() => {\n        showMessage(\n          'This withdrawal is taking longer than expected. Please wait…'\n        );\n      }, 10000);\n    },\n\n    onSuccess: async (result: PayoutDropInSubmitResult) => {\n      if (loadingTimeout) {\n        clearTimeout(loadingTimeout);\n      }\n      setLoadingState(false);\n\n      const verification = await fetch('/api/verify-payout', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({\n          systemTransactionId: result.systemTransactionId,\n          merchantTransactionId: result.merchantTransactionId,\n          payoutMethod: result.payoutMethod,\n          payouts: result.payouts,\n        }),\n      }).then((response) => response.json());\n\n      if (verification.success) {\n        window.location.href = `/withdrawals/${verification.id}/status`;\n        return;\n      }\n\n      showMessage(\n        \"We couldn't verify this withdrawal yet. Please contact support with your reference.\"\n      );\n    },\n\n    onError: (error: BaseSdkException) => {\n      if (loadingTimeout) {\n        clearTimeout(loadingTimeout);\n      }\n      setLoadingState(false);\n\n      console.error('Payout failed:', error.ErrorCode, error.message);\n\n      if (error.ErrorCode === 'SDK1701') {\n        showMessage('No withdrawal methods are available for your account.');\n        return;\n      }\n\n      if (error.ErrorCode === 'SDK1700') {\n        showMessage(\n          \"We couldn't load withdrawal settings. Please refresh or try again later.\"\n        );\n        return;\n      }\n\n      showMessage(\n        \"We couldn't complete your withdrawal. Please try again or contact support.\"\n      );\n    },\n\n    analyticsEvent: (event) => {\n      console.log(event.eventName, event.sessionId);\n    },\n  });\n\n  await payoutDropIn.create('payout-drop-in-container');\n}\n","lang":"typescript"},"children":[]}]},"headings":[{"value":"Events","id":"events","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Supported events","id":"supported-events","depth":2},{"value":"onGetShopper","id":"ongetshopper","depth":3},{"value":"Event data","id":"event-data","depth":4},{"value":"Return value","id":"return-value","depth":4},{"value":"Example implementation","id":"example-implementation","depth":4},{"value":"onBeforeSubmit","id":"onbeforesubmit","depth":3},{"value":"Event data","id":"event-data-1","depth":4},{"value":"Return value","id":"return-value-1","depth":4},{"value":"Example implementation","id":"example-implementation-1","depth":4},{"value":"onSubmit","id":"onsubmit","depth":3},{"value":"Event data","id":"event-data-2","depth":4},{"value":"Example implementation","id":"example-implementation-2","depth":4},{"value":"onSuccess","id":"onsuccess","depth":3},{"value":"Event data","id":"event-data-3","depth":4},{"value":"Example implementation","id":"example-implementation-3","depth":4},{"value":"onError","id":"onerror","depth":3},{"value":"Event data","id":"event-data-4","depth":4},{"value":"Common error scenarios","id":"common-error-scenarios","depth":4},{"value":"Example implementation","id":"example-implementation-4","depth":4},{"value":"analyticsEvent","id":"analyticsevent","depth":3},{"value":"Example implementation","id":"example-implementation-5","depth":4},{"value":"Event data structures","id":"event-data-structures","depth":2},{"value":"PayoutMethod","id":"payoutmethod","depth":3},{"value":"PayoutDropInSubmitResult interface","id":"payoutdropinsubmitresult-interface","depth":3},{"value":"BaseSdkException interface","id":"basesdkexception-interface","depth":3},{"value":"Shopper interface","id":"shopper-interface","depth":3},{"value":"Error handling in events","id":"error-handling-in-events","depth":2},{"value":"Callback execution order","id":"callback-execution-order","depth":2},{"value":"Card, Apple Pay, and Google Pay","id":"card-apple-pay-and-google-pay","depth":3},{"value":"PayPal","id":"paypal","depth":3},{"value":"Mount failures","id":"mount-failures","depth":3},{"value":"Complete integration example","id":"complete-integration-example","depth":2}],"frontmatter":{"seo":{"title":"Events"}},"lastModified":"2026-11-12T15:20:37.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/payout/drop-in/web/events","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}