Skip to content

How it works

Learn how Payout Drop-in selects methods, renders the accordion, and completes a withdrawal.

Overview

Payout Drop-in is a single withdrawal component that orchestrates Card, PayPal, Apple Pay, and Google Pay for returning shoppers. It reuses the Web SDK's secure payout paths and presents eligible stored instruments in a vertical accordion.

Drop-in doesn't collect new card primary account numbers for first-time vaulting. Shoppers must already have an eligible stored instrument or a linked PayPal account before a method appears.

Key benefits

Drop-in gives you these benefits:

  • Pre-built accordion: One mount point for eligible payout methods instead of wiring each component yourself.
  • Session-driven methods: Candidate methods come from the payout Session allowedFundingTypes.
  • Instrument-aware UI: Methods appear only when the shopper still has an eligible token or PayPal association after filtering.
  • Shared callbacks: Use onSuccess, onError, and optional hooks across methods (with PayPal-specific differences documented in the method guides).
  • Portal branding: Colours, fonts, and method order come from the payout Drop-in site configuration.

Integration steps

A full Web integration involves these high-level steps:

  1. Set up the Unity Portal: Activate the Payout Drop-in service and related payout method services, enable methods, configure branding, whitelist domains where Drop-in is hosted, and set up webhooks for payout verification.
  2. Prepare shopper instruments: Ensure returning shoppers have vaulted cards, Apple Pay or Google Pay device tokens, or a linked PayPal account for the methods you enable.
  3. Install the SDK: Install @pxpio/web-components-sdk and import PayoutDropIn from the package root.
  4. Create a payout session: On your backend, create a session with serviceType: "PayoutDropIn" and payout intents for each method you enable. Keep inbound credentials on the server.
  5. Embed Drop-in: Initialise with the session, ownerId, transaction data, and callbacks, then call create(containerId).
  6. Verify on your backend: Treat onSuccess as submission acknowledgement. Confirm the payout with merchant transaction webhooks or a server-side lookup before marking the withdrawal complete.

Ready to integrate? Follow the Web SDK quickstart, or see Implementation for the full mount and reconciliation pattern.

How method visibility is decided

At mount time, Drop-in:

  1. Reads the session allowedFundingTypes to build a candidate method list.
  2. Loads the site payout configuration (branding, labels, payment method order).
  3. Loads shopper-specific data (active card tokens and, when needed, PayPal wallet association).
  4. Filters by instrument type, expiry, and optional merchant blacklists.
  5. Renders an accordion of methods that still have something to pay out to.
  6. If nothing remains, reports SDK1701 through onError.

The following table maps each method to its session signal and shopper requirement.

MethodSession signalShopper requirement
CardallowedFundingTypes.cards is present (including an empty array). cardSchemes alone doesn't enable card.The shopper ID plus at least one eligible plain-card token.
Apple PayallowedFundingTypes.wallets.applePayThe shopper ID plus at least one Apple Pay device token (panType: Device).
Google PayallowedFundingTypes.wallets.googlePayThe shopper ID plus at least one Google Pay device token (panType: Device).
PayPalallowedFundingTypes.wallets.paypalThe shopper ID plus an active PayPal wallet association.

See the Payout method overview for filtering detail and per-method behaviour.

UI behaviour

Drop-in uses a vertical accordion:

  • Eligible methods appear as expandable panels.
  • Only one method is expanded at a time where the accordion controls expansion.
  • Method order follows the site payout configuration when a manual order is set. Otherwise, Drop-in uses its default order among the common methods.
  • Loading and empty states are handled in the mount container, including configuration failures (SDK1700) and no eligible methods (SDK1701).

Success and verification

When a payout submission succeeds, onSuccess receives transaction identifiers such as systemTransactionId and merchantTransactionId. Always verify on your backend before completing the withdrawal. Payout Drop-in uses the same merchant transaction webhook channel as other products.

See Quickstart for webhook handling patterns and Manage webhooks for subscription and signature validation.

What's next?

Continue with these guides: