{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading","admonition","br","details","required"]},"type":"markdown"},"seo":{"title":"Implementation","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":"implementation","__idx":0},"children":["Implementation"]},{"$$mdtype":"Tag","name":"SubHeading","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Complete guide to integrating Payout Drop-in into your application."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payout Drop-in provides a pre-built withdrawal interface for stored payout instruments. It follows a simple lifecycle:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Initialise:"]}," Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutDropIn.initialize()"]}," with the environment, payout session, transaction data, and callbacks."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Mount:"]}," Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create(containerId)"]}," to load site configuration, resolve instruments, and render payout methods."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handle callbacks:"]}," Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},", and optional hooks to drive your UX and backend reconciliation."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in shows methods only when the session allows them and the shopper has an eligible stored instrument after filtering (expiry, wallet type, blacklist, and so on)."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Backend verification is mandatory. Always reconcile payout status on your merchant backend before completing a withdrawal. Frontend callbacks can be manipulated and aren't proof of settlement."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-start","__idx":2},"children":["Before you start"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Complete these prerequisites:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Activate ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payout Drop-in"]}," for the site in the Unity Portal. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/activation"},"children":["Activation"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Configure the allowed payout methods and branding for the site. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/payout-methods"},"children":["Payout methods"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/branding"},"children":["Branding"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure test shoppers have eligible stored instruments (or plan to test empty-state and error paths). See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/onboarding"},"children":["Onboarding"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Get the inbound API credentials (client ID and token) required for session creation. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/authentication"},"children":["Authentication"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-install-the-web-sdk-library","__idx":3},"children":["Step 1: Install the Web SDK library"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Install the latest version of the Web SDK from the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://www.npmjs.com/package/@pxpio/web-components-sdk","target":"_blank"},"children":["npm public registry"]},". You'll need Node.js 22.x or higher for the frontend package installation."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"npm i @pxpio/web-components-sdk\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import {\n  PayoutDropIn,\n  type PayoutDropInSubmitResult,\n} from '@pxpio/web-components-sdk';\nimport type { BaseSdkException } from '@pxpio/web-components-sdk';\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Import from the package root and avoid deep ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/src/"]}," paths in merchant applications, unless your build pipeline requires them."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-get-your-api-credentials","__idx":4},"children":["Step 2: Get your API credentials"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Session creation uses HMAC authentication. Keep credentials on your backend only."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To get your credentials:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://portal.pxp.io","target":"_blank"},"children":["Unity Portal"]},", go to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant setup > Merchant groups"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select the merchant group that owns the site."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Inbound calls"]}," tab."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Copy the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Client ID"]}," in the top-right corner."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["New token"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Choose a number of days before token expiry. For example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["30"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save"]},". Copy the token ID and token value."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rotate tokens on a regular schedule. Store values in server-side secrets only. Never ship token values to the browser."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-create-a-payout-session-on-your-backend","__idx":5},"children":["Step 3: Create a payout session on your backend"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payout Drop-in requires a session from the Sessions API. Create it on your backend with HMAC authentication so inbound credentials stay secure."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"understanding-hmac-authentication","__idx":6},"children":["Understanding HMAC authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The platform uses HMAC-SHA256. Concatenate these values in order, with no separators:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Timestamp:"]}," The current time in ",{"$$mdtype":"Tag","name":"a","attributes":{"target":"_blank","href":"https://en.wikipedia.org/wiki/Unix_time"},"children":["Unix seconds"]}," (UTC)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request ID:"]}," A unique GUID for this request"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request path:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api/v1/sessions"]}," (no leading slash)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request body:"]}," The complete JSON request body as a minified string"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{timestamp}{requestId}{requestPath}{requestBody}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create an HMAC SHA256 hash of that string using your token value as the secret key. Encode the digest as uppercase hex."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When creating the HMAC signature, the request body must be minified (no whitespace or formatting). Formatted JSON in these docs is for readability only."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"session-request-parameters","__idx":7},"children":["Session request parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use these fields when you create the session:"]},{"$$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":["merchant"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string (≤ 20 characters)"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your merchant identifier from the Unity Portal (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant setup > Merchants"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["site"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string (≤ 100 characters)"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your site identifier from the Unity Portal (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant setup > Sites"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string (≤ 50 characters)"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A unique ID for this withdrawal attempt."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionTimeout"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["number"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The session lifetime in minutes (≥ 1)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amounts.currencyCode"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string (3 characters)"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The ISO 4217 currency code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amounts.transactionValue"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The withdrawal amount."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionMethod.intent"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["At least one intent property. For Payout Drop-in, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Payout"]}," on each method you enable (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paypal"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowTransaction"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["boolean"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether the session may proceed with transactions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["serviceType"]},{"$$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":["Must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"PayoutDropIn\""]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerProfileId"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string (≤ 255 characters)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A customer profile ID. When present, the session service can apply customer profile method allow lists and limits from Payout Drop-in configuration."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example body is formatted for reading. Minify it before you sign the request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"merchant\": \"MERCHANT-1\",\n  \"site\": \"SITE-1\",\n  \"sessionTimeout\": 120,\n  \"merchantTransactionId\": \"0ce72cfd-014d-4256-a006-a56601b2ffc4\",\n  \"amounts\": {\n    \"currencyCode\": \"USD\",\n    \"transactionValue\": 25.0\n  },\n  \"transactionMethod\": {\n    \"intent\": {\n      \"card\": \"Payout\",\n      \"paypal\": \"Payout\"\n    }\n  },\n  \"allowTransaction\": true,\n  \"serviceType\": \"PayoutDropIn\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"prepare-and-send-your-request","__idx":8},"children":["Prepare and send your request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header follows this format:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"PXP-UST1 {tokenId}:{timestamp}:{signature}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example curl (the JSON body string must match the payload you signed exactly):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"curl","header":{"controls":{"copy":{}}},"source":"curl -i -X POST \\\n  'https://api-services.pxp.io/api/v1/sessions' \\\n  -H 'Authorization: PXP-UST1 {tokenId}:{timestamp}:{signature}' \\\n  -H 'X-Request-Id: {requestId}' \\\n  -H 'X-Client-Id: {clientId}' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"merchant\":\"MERCHANT-1\",\"site\":\"SITE-1\",\"sessionTimeout\":120,\"merchantTransactionId\":\"0ce72cfd-014d-4256-a006-a56601b2ffc4\",\"amounts\":{\"currencyCode\":\"USD\",\"transactionValue\":25},\"transactionMethod\":{\"intent\":{\"card\":\"Payout\",\"paypal\":\"Payout\"}},\"allowTransaction\":true,\"serviceType\":\"PayoutDropIn\"}'\n","lang":"curl"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Validate the shopper and withdrawal on your server before calling the Sessions API. Return session data only to that authenticated shopper."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"session-response","__idx":9},"children":["Session response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On success you receive HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," with session properties such as:"]},{"$$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":"Use"},"children":["Use"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The SDK session identity."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hmacKey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The session-scoped Unity API authentication key (not your inbound API token)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptionKey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The encryption key for sensitive SDK payloads."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionExpiry"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The session lifetime."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedFundingTypes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Which payout methods the SDK may consider."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["restrictions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Session restrictions when returned."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isClosedLoopEnforced"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", Drop-in can enter closed-loop enforcement UI where configured."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example shape (values vary by site):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"sessionId\": \"c5f0799b-0839-43ce-abc5-5b462a98f250\",\n  \"hmacKey\": \"904bc42395d4af634e2fd48ee8c2c7f52955a1da97a3aa3d82957ff12980a7bb\",\n  \"encryptionKey\": \"20d175a669ad3f8c195c9c283fc86155\",\n  \"sessionExpiry\": \"2025-05-19T13:39:20.3843454Z\",\n  \"allowedFundingTypes\": {\n    \"cardSchemes\": [\"Visa\", \"Mastercard\"],\n    \"cards\": [],\n    \"wallets\": {\n      \"paypal\": {},\n      \"applePay\": {},\n      \"googlePay\": {}\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedFundingTypes"]}," gates candidate methods only. Card requires the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cards"]}," field to be present (including an empty array). ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardSchemes"]}," alone doesn't enable it. Wallet objects may also include provider metadata such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantId"]}," when those methods are enabled for the site. Eligible stored instruments and PayPal wallet state still determine what the shopper sees."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Return the Sessions API JSON as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session"]},", plus ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData"]}," with the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]}," used to create the session."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-initialise-payout-drop-in-on-your-frontend","__idx":10},"children":["Step 4: Initialise Payout Drop-in on your frontend"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pass the session and matching transaction data into ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutDropIn.initialize()"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import {\n  PayoutDropIn,\n  type PayoutDropInSubmitResult,\n} from '@pxpio/web-components-sdk';\nimport type { BaseSdkException } from '@pxpio/web-components-sdk';\n\nconst { session, transactionData } = await fetch('/api/create-session', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({\n    amount: 25,\n    currency: 'USD',\n  }),\n}).then((response) => response.json());\n\nconst payoutDropIn = PayoutDropIn.initialize({\n  environment: 'test',\n  session,\n  ownerId: 'YOUR-MERCHANT-GROUP-ID',\n  transactionData: {\n    currency: transactionData.currency,\n    amount: transactionData.amount,\n    entryType: 'Ecom',\n    merchantTransactionId: transactionData.merchantTransactionId,\n    merchantTransactionDate: () => new Date().toISOString(),\n  },\n  onGetShopper: async () => ({ id: 'authenticated-shopper-id' }),\n  onBeforeSubmit: async (payoutMethod) => {\n    console.log('About to submit:', payoutMethod);\n    return true;\n  },\n  onSubmit: (payoutMethod) => {\n    console.log('Submit started:', payoutMethod);\n  },\n  onSuccess: async (result: PayoutDropInSubmitResult) => {\n    await verifyPayoutOnBackend(result);\n  },\n  onError: (error: BaseSdkException) => {\n    console.error(error.ErrorCode, error.message);\n  },\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configuration-parameters","__idx":11},"children":["Configuration parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use these required properties when you initialise Drop-in:"]},{"$$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":["environment"]},{"$$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 environment value: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["test"]}," for development and testing, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["live"]}," for production."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["SessionData"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The session object from your backend, including ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hmacKey"]},", and usually ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedFundingTypes"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ownerId"]},{"$$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 merchant ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["group"]}," ID used for token vault lookups."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The amount, currency, entry type, and merchant transaction identifiers. Match the session amounts and ID."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.currency"]},{"$$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 ISO 4217 currency code. Match the session currency."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.amount"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The payout amount. Match the session amount."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.entryType"]},{"$$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 channel: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Ecom"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Moto"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.merchantTransactionId"]},{"$$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 same ID used when creating the session."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData.merchantTransactionDate"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["function"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A function that returns an ISO 8601 timestamp string."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["function"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A strongly recommended callback that returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Promise<{ id: string }>"]}," for vault and PayPal lookups."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBeforeSubmit"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["function"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A callback for card, Apple Pay, and Google Pay only. Return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," to cancel."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmit"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["function"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A callback for card, Apple Pay, and Google Pay only. Fires when card-on-file submit starts."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["function"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The callback fires after successful SDK payout submission."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["function"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The callback fires for configuration, empty-method, and payout failures on the SDK error path."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ownerType"]}," is set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MerchantGroup"]}," inside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutDropIn.initialize()"]},", so you don't need to pass it. Don't pass payment intents on frontend ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData"]},": the SDK sets payout intents internally. Session intents are fixed when you create the session with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Payout"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/web/configuration"},"children":["Configuration"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["methodConfig"]},", localisation, closed-loop options, and the full reference."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-mount-drop-in-to-your-page","__idx":12},"children":["Step 5: Mount Drop-in to your page"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add a container element:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"<div id=\"payout-drop-in-container\"></div>\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Then mount:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"try {\n  await payoutDropIn.create('payout-drop-in-container');\n} catch (error) {\n  console.error('Mount failed:', error);\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["During ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]},", Drop-in:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Shows a loading shell in the container."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Calls ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," (if provided)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Loads payout Drop-in site configuration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Resolves stored card or wallet tokens and PayPal association where applicable."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Renders available methods in an accordion, ordered from the site configuration. For the methods covered in these guides, the relative default order is card, Apple Pay, Google Pay, then PayPal. Other enabled methods can appear in the default list between or after those entries."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1700"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1701"]}," through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," when configuration fails or no methods remain. In those cases ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," usually settles without throwing."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["destroy()"]}," when the page or route unmounts to clear components and container shell markup."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Catch synchronous throws from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initialize()"]}," (missing session fields) and promise rejections from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," (e.g., a rejected ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]},"). Those paths don't always call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-6-handle-callbacks","__idx":13},"children":["Step 6: Handle callbacks"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"ongetshopper","__idx":14},"children":["onGetShopper"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Return the authenticated shopper ID used for vault and PayPal lookups:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"onGetShopper: async () => {\n  const user = await getAuthenticatedUser();\n  return { id: user.shopperId };\n},\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"onsuccess","__idx":15},"children":["onSuccess"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Treat this as submission acknowledgement only. Verify on your backend before updating withdrawal status:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"onSuccess: async (result: PayoutDropInSubmitResult) => {\n  const verified = 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 (verified.success) {\n    window.location.href = `/withdrawals/${verified.id}/status`;\n  }\n},\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"onerror","__idx":16},"children":["onError"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Map ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ErrorCode"]}," to shopper-safe messages. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/web/error-handling"},"children":["Error handling"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"onError: (error: BaseSdkException) => {\n  console.error(error.ErrorCode, error.message, error.details);\n  showErrorMessage(mapToCustomerSafeMessage(error));\n},\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Full callback behaviour and ordering are documented in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/web/events"},"children":["Events"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"integration-architecture","__idx":17},"children":["Integration architecture"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A typical Web integration follows this sequence:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The shopper opens your payout page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your frontend requests payout context from your backend."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your backend creates a payout session with HMAC authentication and returns session data plus matching transaction details."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your frontend calls ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutDropIn.initialize()"]}," and then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create(containerId)"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The SDK loads payout Drop-in configuration, active tokens, and wallet associations as needed, then renders eligible methods."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The shopper submits a payout. The SDK calls PXP payout APIs and delivers ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your frontend asks your backend to reconcile payout status before updating the withdrawal."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"method-availability-logic","__idx":18},"children":["Method availability logic"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in builds a candidate list from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedFundingTypes"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Card:"]}," When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedFundingTypes.cards"]}," is present (including ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[]"]},"). ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardSchemes"]}," alone isn't enough."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Apple Pay and Google Pay:"]}," When the corresponding ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wallets.applePay"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wallets.googlePay"]}," entry exists."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PayPal:"]}," When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wallets.paypal"]}," is allowed and an active linked PayPal account is returned for the shopper."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Then Drop-in:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Applies merchant ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["methodConfig"]}," blacklists."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Builds card-on-file bundles and drops card, Apple Pay, or Google Pay when no visible tokens remain."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Orders methods using site branding configuration (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["manualOrder"]}," when set; otherwise the SDK default order)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If no methods remain after mount filtering, reports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1701"]}," through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"card-on-file-payout-flow","__idx":19},"children":["Card-on-file payout flow"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This flow applies to card, Apple Pay, and Google Pay."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Card-on-file submit runs in this order:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The shopper selects a stored token and confirms withdrawal."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBeforeSubmit"]}," runs. Return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," to cancel."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSubmit"]}," fires when card-on-file submit starts."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The payout initiation completes with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["PayPal uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," only. The card-on-file UI can allow delete token and edit expiry where enabled; CVC isn't required on this payout submit path."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"backend-verification","__idx":20},"children":["Backend verification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before marking a withdrawal complete:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm the transaction exists. Query by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["systemTransactionId"]},", or each ID in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payouts"]}," for closed-loop."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Match the amount and currency to the authorised withdrawal."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Match ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]}," to your internal withdrawal record."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deduplicate webhook or callback delivery using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["systemTransactionId"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/web/quickstart"},"children":["Quickstart"]}," for an end-to-end pattern and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/web/testing"},"children":["Testing"]}," for a pre-production checklist."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"merchant-responsibilities","__idx":21},"children":["Merchant responsibilities"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"backend","__idx":22},"children":["Backend"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On the backend:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Authenticate shoppers and authorise withdrawals."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create payout sessions with validated amounts and profiles."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep inbound API tokens secret."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reconcile payout state via webhooks or the Transactions API."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"frontend","__idx":23},"children":["Frontend"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On the frontend:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fetch session data from your backend only."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pass an authenticated shopper ID via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Handle callbacks and call backend verification endpoints."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Destroy Drop-in instances on navigation unmount."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"whats-next","__idx":24},"children":["What's next?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Continue with these guides:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/web/configuration"},"children":["Configuration"]},": Review the full initialiser reference."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/web/events"},"children":["Events"]},": Handle callback details and ordering."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/web/error-handling"},"children":["Error handling"]},": Recover from SDK error codes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/web/troubleshooting"},"children":["Troubleshooting"]},": Diagnose common symptoms."]}]}]},"headings":[{"value":"Implementation","id":"implementation","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Before you start","id":"before-you-start","depth":2},{"value":"Step 1: Install the Web SDK library","id":"step-1-install-the-web-sdk-library","depth":2},{"value":"Step 2: Get your API credentials","id":"step-2-get-your-api-credentials","depth":2},{"value":"Step 3: Create a payout session on your backend","id":"step-3-create-a-payout-session-on-your-backend","depth":2},{"value":"Understanding HMAC authentication","id":"understanding-hmac-authentication","depth":3},{"value":"Session request parameters","id":"session-request-parameters","depth":3},{"value":"Prepare and send your request","id":"prepare-and-send-your-request","depth":3},{"value":"Session response","id":"session-response","depth":3},{"value":"Step 4: Initialise Payout Drop-in on your frontend","id":"step-4-initialise-payout-drop-in-on-your-frontend","depth":2},{"value":"Configuration parameters","id":"configuration-parameters","depth":3},{"value":"Step 5: Mount Drop-in to your page","id":"step-5-mount-drop-in-to-your-page","depth":2},{"value":"Step 6: Handle callbacks","id":"step-6-handle-callbacks","depth":2},{"value":"onGetShopper","id":"ongetshopper","depth":3},{"value":"onSuccess","id":"onsuccess","depth":3},{"value":"onError","id":"onerror","depth":3},{"value":"Integration architecture","id":"integration-architecture","depth":2},{"value":"Method availability logic","id":"method-availability-logic","depth":2},{"value":"Card-on-file payout flow","id":"card-on-file-payout-flow","depth":2},{"value":"Backend verification","id":"backend-verification","depth":2},{"value":"Merchant responsibilities","id":"merchant-responsibilities","depth":2},{"value":"Backend","id":"backend","depth":3},{"value":"Frontend","id":"frontend","depth":3},{"value":"What's next?","id":"whats-next","depth":2}],"frontmatter":{"seo":{"title":"Implementation"}},"lastModified":"2026-11-12T15:20:37.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/payout/drop-in/web/implementation","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}