Learn how Payout Drop-in selects methods, renders the accordion, and completes a withdrawal.
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.
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.
A full Web integration involves these high-level steps:
- 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.
- 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.
- Install the SDK: Install
@pxpio/web-components-sdkand importPayoutDropInfrom the package root. - 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. - Embed Drop-in: Initialise with the session,
ownerId, transaction data, and callbacks, then callcreate(containerId). - Verify on your backend: Treat
onSuccessas 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.
At mount time, Drop-in:
- Reads the session
allowedFundingTypesto build a candidate method list. - Loads the site payout configuration (branding, labels, payment method order).
- Loads shopper-specific data (active card tokens and, when needed, PayPal wallet association).
- Filters by instrument type, expiry, and optional merchant blacklists.
- Renders an accordion of methods that still have something to pay out to.
- If nothing remains, reports
SDK1701throughonError.
The following table maps each method to its session signal and shopper requirement.
| Method | Session signal | Shopper requirement |
|---|---|---|
| Card | allowedFundingTypes.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 Pay | allowedFundingTypes.wallets.applePay | The shopper ID plus at least one Apple Pay device token (panType: Device). |
| Google Pay | allowedFundingTypes.wallets.googlePay | The shopper ID plus at least one Google Pay device token (panType: Device). |
| PayPal | allowedFundingTypes.wallets.paypal | The shopper ID plus an active PayPal wallet association. |
See the Payout method overview for filtering detail and per-method 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).
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.
Continue with these guides:
- Activation: Enable Payout Drop-in in the Unity Portal.
- Onboarding: Prepare vaulted instruments and linked wallets.
- Web SDK quickstart: Follow our end-to-end sandbox walkthrough.