Configure Payout Drop-in once at initialisation for environment, session, transaction data, callbacks, and method options.
Payout Drop-in uses a single configuration object passed to PayoutDropIn.initialize(). You only configure Drop-in once. It then loads site branding and method order from Unity, reads funding permissions from the payout session, and renders only methods that still have eligible stored instruments after filtering.
You typically configure:
- Session data: Which funding types are allowed for this withdrawal.
transactionData: Amount, currency, and your merchant transaction identifiers.- Callbacks: Shopper identity, success and error handling, and optional submit hooks.
methodConfig: Optional instrument blacklists.localisation.payoutDropIn: Optional copy overrides.
Branding colours, fonts, and method order usually come from the payout configuration API rather than custom CSS.
The following example shows a complete initialiser shape with required fields and common optional callbacks:
import {
PayoutDropIn,
type PayoutDropInSubmitResult,
type PayoutDropInMethodConfig,
} from '@pxpio/web-components-sdk';
import type { BaseSdkException } from '@pxpio/web-components-sdk';
const methodConfig: PayoutDropInMethodConfig = {
card: {
blacklistedInstruments: {
gatewayTokenIds: ['token-to-hide'],
},
},
paypal: {
blacklistedPayerId: 'payer-id-to-hide',
},
};
const payoutDropIn = PayoutDropIn.initialize({
environment: 'test',
session: sessionData,
ownerId: 'YOUR-MERCHANT-GROUP-ID',
transactionData: {
currency: 'USD',
amount: 25,
entryType: 'Ecom',
merchantTransactionId: 'withdrawal-123',
merchantTransactionDate: () => new Date().toISOString(),
},
onGetShopper: () => Promise.resolve({ id: 'shopper-123' }),
onSuccess: (result: PayoutDropInSubmitResult) => {
void verifyPayoutOnBackend(result);
},
onError: (error: BaseSdkException) => {
console.error(error.ErrorCode, error.message);
},
onBeforeSubmit: async (payoutMethod) => {
console.log('About to submit:', payoutMethod);
return true;
},
onSubmit: (payoutMethod) => {
console.log('Submit started:', payoutMethod);
},
analyticsEvent: (event) => {
console.log(event.eventName, event.sessionId);
},
methodConfig,
localisation: {
payoutDropIn: {
loadingText: 'Loading withdrawal methods…',
cardLabel: 'Debit or credit card',
},
},
});
await payoutDropIn.create('payout-drop-in-container');PayoutDropIn.initialize() returns an instance with:
| Method | Description |
|---|---|
create(containerId) | The method that mounts Drop-in into a DOM element by ID. |
destroy() | The method that unmounts Drop-in and clears loading or error shells in the container. |
getComponent() | Advanced access to the underlying component instance. |
Set the Unity environment for the Drop-in instance:
environment: 'test' // or 'live'Use one of these values:
| Value | Description |
|---|---|
test | The sandbox Unity environment for development and QA. |
live | The production Unity environment. |
Use test with test site configuration and test instruments until you complete Testing.
Pass the payout session object returned by your backend:
session: sessionDataRequired session fields for SDK operation:
| Field | Description |
|---|---|
sessionIdrequired | The session identifier for Unity API calls. |
hmacKeyrequired | The session HMAC secret (validated at initialise). |
encryptionKeyrequired | The key used for encrypted SDK payloads. |
Common optional session fields:
| Field | Description |
|---|---|
allowedFundingTypes | The funding types that gate which payout methods can appear. Card requires cards to be present. Wallets use wallets.paypal, wallets.applePay, and wallets.googlePay. |
isClosedLoopEnforced | Whether Drop-in loads closed-loop allocation and enforcement UI where configured. |
restrictions | A shared restrictions object on the session. |
A method allowed on the session still appears only when the shopper has an eligible stored instrument after filtering.
Create the session on your backend. See Quickstart and Implementation.
Pass the merchant group ID used for token vault lookups:
ownerId: 'YOUR-MERCHANT-GROUP-ID'ownerType is set to MerchantGroup during initialisation. Token vault requests use ownerType and ownerId when retrieving active tokens.
Don't pass payment intents on transactionData. The SDK sets payout intents (card, paypal, and related intents) to Payout internally.
The following properties are required on transactionData:
| Property | Description |
|---|---|
currencystring required | The ISO 4217 currency code. Match the currency on the Payout Session. |
amountnumber required | The payout amount. Match the amount on the payout session. |
entryTypeEcom or Motorequired | The channel for the payout. |
merchantTransactionIdstring required | Your withdrawal correlation ID. |
merchantTransactionDate() => stringrequired | A function that returns an ISO 8601 timestamp. |
Generate a unique ID per withdrawal attempt:
merchantTransactionId: crypto.randomUUID()
// or
merchantTransactionId: `withdrawal-${internalId}`These callbacks are required on PayoutDropIn.initialize():
| Callback | Signature | Description |
|---|---|---|
onSuccessrequired | (result: PayoutDropInSubmitResult) => void | The callback fires after successful SDK payout submission. |
onErrorrequired | (error: BaseSdkException) => void | The callback fires for configuration, empty-method, and payout failures delivered through the SDK error path. |
PayoutDropInSubmitResult can include:
| Field | Description |
|---|---|
systemTransactionId | The Unity system transaction ID for a single-method payout. |
merchantTransactionId | An echo of your merchant transaction ID when present. |
payoutMethod | The method used (e.g., Card or Paypal) when applicable. |
payouts | The closed-loop results: one entry per created payout transaction. Each entry includes systemTransactionId and merchantTransactionId. When a line isn't Authorised or Pending, it can also include amount, currency, errorCode, and errorReason. |
Treat onSuccess as submission acknowledgement, not confirmation that every closed-loop line settled successfully. Inspect each payouts entry and verify final payout state on your backend before updating withdrawal status.
Some failures occur outside onError (e.g., a rejected onGetShopper promise or synchronous initialise validation). Wrap initialize() and create() in try or catch. See Error handling and Events.
Strongly recommended whenever you expect stored cards, Apple Pay or Google Pay device tokens, or PayPal.
onGetShopper: async () => {
const user = await getAuthenticatedUser();
return { id: user.shopperId };
},The callback must resolve to this field:
| Return field | Description |
|---|---|
idrequired | The shopper ID used for token vault and PayPal wallet association lookups. |
Without a shopper ID, token retrieval is skipped and PayPal can't resolve a linked account. Methods may disappear silently rather than throwing. If the promise rejects, create() rejects. Handle that outside onError.
These optional callbacks control pre-submit validation, loading UI, and analytics:
| Callback | Wired for | Behaviour |
|---|---|---|
onBeforeSubmit |
| The callback receives the PayoutMethod value. Return false (or a promise that resolves to false) to cancel submission. |
onSubmit |
| The callback fires when card-on-file submit starts. |
analyticsEvent | All | An analytics hook. See Analytics. |
PayPal uses onSuccess and onError only. There is no Drop-in onCancel for the PayPal stored panel.
onPayoutMethodChange isn't available on PayoutDropIn.initialize().
Payout-only instrument exclusion for the stored-instrument panels (card, Apple Pay, Google Pay, and PayPal).
| Path | Description |
|---|---|
card.blacklistedInstruments | gatewayTokenIds and schemeTokenIds arrays of token IDs to hide from the card list. |
applePay.blacklistedInstruments | The same object shape as card: gatewayTokenIds and schemeTokenIds arrays of strings that identify Apple Pay device tokens to hide. |
googlePay.blacklistedInstruments | The same object shape as card: gatewayTokenIds and schemeTokenIds arrays of strings that identify Google Pay device tokens to hide. |
paypal.blacklistedPayerId | The payer ID that hides PayPal when it matches the linked account. |
const methodConfig: PayoutDropInMethodConfig = {
card: {
blacklistedInstruments: {
gatewayTokenIds: ['<GATEWAY_TOKEN_ID>'],
schemeTokenIds: ['<SCHEME_TOKEN_ID>'],
},
},
applePay: {
blacklistedInstruments: {
gatewayTokenIds: ['<GATEWAY_TOKEN_ID>'],
},
},
googlePay: {
blacklistedInstruments: {
schemeTokenIds: ['<SCHEME_TOKEN_ID>'],
},
},
paypal: {
blacklistedPayerId: '<PAYPAL_PAYER_ID>',
},
};Blacklists hide instruments or methods in the accordion. When closed-loop enforcement is active, the same values are also sent on the closed-loop allocation request. Always enforce payout eligibility on your backend.
Override merchant-facing strings under localisation.payoutDropIn:
| Key | Purpose |
|---|---|
cardLabel, paypalLabel, applePayLabel, googlePayLabel | The accordion method labels. |
loadingText | The text shown while create() loads configuration. |
noPayoutMethodsError | The message when no methods remain. |
containerAriaLabel, payoutMethodsGroupAriaLabel | The accessibility labels for the Drop-in root and method group. |
payoutMethodExpandedAnnouncement, payoutMethodCollapsedAnnouncement | The screen reader announcements; use {method} as a placeholder. |
cardOnFileTitle, cardOnFileLoadingAriaLabel | The card-on-file panel heading and loading label. |
payoutNotSupportedForCard | The message shown when a Visa or Mastercard token is present but not selectable under gaming payout rules. |
preferredMethodTitle, preferredMethodDescription, preferredMethodAmountLabel, preferredMethodGroupLabel | Copy for the customer-driven preferred-method closed-loop screen. |
mandatoryAllocationTitle, mandatoryAllocationDescription, mandatoryRemainingDescription, mandatorySelectPaymentMethodLabel | Copy for the mandatory allocation closed-loop screen. mandatoryRemainingDescription supports {currency} and {amount} placeholders. |
finalAllocationTitle, finalAllocationDescription, finalAllocationTotalLabel, finalAllocationExcessAmountLabel, finalAllocationExcessGroupLabel, finalAllocationPolicyMessage, finalAllocationPolicyLinkLabel, finalAllocationRejectedMessage, finalAllocationAcceptLabel, finalAllocationBackLabel, finalAllocationContinueLabel | Copy for the final allocation and review closed-loop screens. |
When the session returns isClosedLoopEnforced: true, Drop-in requests closed-loop allocation and site closed-loop configuration during create():
- If allocation succeeds and enforcement is customer-driven, Drop-in opens the preferred-method closed-loop UI.
- If allocation succeeds and enforcement isn't customer-driven, Drop-in opens the mandatory-allocation closed-loop UI.
- If allocation doesn't succeed (without throwing), Drop-in falls back to the standard payout accordion and doesn't call
onErrorfor that fallback. - If allocation or closed-loop config retrieval throws, Drop-in calls
onError(typicallySDK0000) and shows an error shell in the container.
You can configure the informational banner with closedLoopConfig:
closedLoopConfig: {
helpUrl: 'https://example.com/payout-policy',
hideInformationBanner: false,
},These properties control the banner:
| Property | Description |
|---|---|
helpUrl | A help or FAQ URL opened from the closed-loop policy banner. |
hideInformationBanner | When true, hides the informational banner. Defaults to false. |
Closed-loop submit still delivers results through onSuccess or onError. For onSuccess, inspect every entry in payouts: lines that aren't Authorised or Pending can include errorCode and errorReason. Submit failures on the closed-loop path can also raise SDK1703 with PayoutDropInCardPayoutFailedSdkException (message typically Card payout failed.), even when more than one instrument was involved.
These properties come from the shared Web SDK config surface. Most Payout Drop-in integrations leave them unset.
| Property | Description |
|---|---|
paypalConfig | The stored PayPal panel overlays linked email and payer ID from wallet association and sets SDK-driven submit, so you typically don't need to supply this for that panel. |
kountDisabled | When false (default), Kount remains enabled on card-on-file submit where risk screening data is applied. |
clientName, siteName | Display names forwarded to provider experiences that support them. |
restrictions | A shared restrictions object on the SDK config. For payout card-on-file lists, use methodConfig blacklists to hide instruments in the accordion (and on closed-loop allocation when enforcement is active). |
Many behaviours are controlled in the Unity Portal and Sessions API rather than in frontend code.
Controlled by session allowedFundingTypes and shopper instruments. Example session fragment:
{
"allowedFundingTypes": {
"cards": [],
"cardSchemes": ["Visa", "Mastercard"],
"wallets": {
"paypal": {},
"applePay": {},
"googlePay": {}
}
}
}The session response may also include wallet metadata such as merchantId when those methods are enabled for the site. The SDK treats a wallet method as a candidate when its wallet object is present.
Remember:
- Card requires
allowedFundingTypes.cardsto be present (including[]).cardSchemesalone doesn't enable card. - Wallet methods need their wallet entry and an eligible stored instrument.
Fetched from GET /api/v1/payout-dropin/configurations. When site config includes a manual payment-method order, Drop-in applies that order. Otherwise it uses the SDK default order. For the methods covered in these guides, that relative order is card, Apple Pay, Google Pay, then PayPal. Other enabled methods can appear in the default list between or after those entries.
Use this pattern when you only need required fields and backend verification:
const payoutDropIn = PayoutDropIn.initialize({
environment: 'test',
session: sessionData,
ownerId: 'YOUR-MERCHANT-GROUP-ID',
transactionData: {
currency: 'USD',
amount: 25,
entryType: 'Ecom',
merchantTransactionId: crypto.randomUUID(),
merchantTransactionDate: () => new Date().toISOString(),
},
onGetShopper: () => Promise.resolve({ id: 'shopper-123' }),
onSuccess: (result) => {
void fetch('/api/verify-payout', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(result),
});
},
onError: (error) => {
console.error(error.ErrorCode, error.message);
},
});
await payoutDropIn.create('payout-drop-in-container');Use this pattern when you also need blacklists, localisation, and submit hooks:
const payoutDropIn = PayoutDropIn.initialize({
environment: 'live',
session: sessionData,
ownerId: 'YOUR-MERCHANT-GROUP-ID',
transactionData: {
currency: 'USD',
amount: 100,
entryType: 'Ecom',
merchantTransactionId: `wd-${withdrawalId}`,
merchantTransactionDate: () => new Date().toISOString(),
},
onGetShopper: async () => ({ id: (await getUser()).shopperId }),
onBeforeSubmit: async (payoutMethod) => {
const allowed = await fetch('/api/withdrawal-allowed', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ withdrawalId, payoutMethod }),
}).then((r) => r.json());
return allowed.ok;
},
onSubmit: () => {
document.getElementById('payout-loading')!.hidden = false;
},
onSuccess: async (result) => {
document.getElementById('payout-loading')!.hidden = true;
await reconcileWithdrawal(result);
},
onError: (error) => {
document.getElementById('payout-loading')!.hidden = true;
showSafeError(error.ErrorCode);
},
analyticsEvent: (event) => {
sendToAnalytics(event);
},
methodConfig: {
card: {
blacklistedInstruments: {
gatewayTokenIds: blockedTokens,
},
},
},
localisation: {
payoutDropIn: {
loadingText: 'Preparing your withdrawal options…',
},
},
closedLoopConfig: {
helpUrl: 'https://example.com/payout-policy',
},
});
await payoutDropIn.create('payout-drop-in-container');