Skip to content

Configuration

Configure Payout Drop-in once at initialisation for environment, session, transaction data, callbacks, and method options.

Overview

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.

Configuration structure

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.

Required configuration

Environment

Set the Unity environment for the Drop-in instance:

environment: 'test' // or 'live'

Use one of these values:

ValueDescription
testThe sandbox Unity environment for development and QA.
liveThe production Unity environment.

Use test with test site configuration and test instruments until you complete Testing.

Session data

Pass the payout session object returned by your backend:

session: sessionData

Required session fields for SDK operation:

FieldDescription
sessionId
required
The session identifier for Unity API calls.
hmacKey
required
The session HMAC secret (validated at initialise).
encryptionKey
required
The key used for encrypted SDK payloads.

Common optional session fields:

Field Description
allowedFundingTypesThe funding types that gate which payout methods can appear. Card requires cards to be present. Wallets use wallets.paypal, wallets.applePay, and wallets.googlePay.
isClosedLoopEnforcedWhether Drop-in loads closed-loop allocation and enforcement UI where configured.
restrictionsA 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.

Owner identification

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.

Transaction data

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:

PropertyDescription
currency
string
required
The ISO 4217 currency code. Match the currency on the Payout Session.
amount
number
required
The payout amount. Match the amount on the payout session.
entryType
Ecom or Moto
required
The channel for the payout.
merchantTransactionId
string
required
Your withdrawal correlation ID.
merchantTransactionDate
() => string
required
A function that returns an ISO 8601 timestamp.

Merchant transaction ID

Generate a unique ID per withdrawal attempt:

merchantTransactionId: crypto.randomUUID()
// or
merchantTransactionId: `withdrawal-${internalId}`

Required callbacks

These callbacks are required on PayoutDropIn.initialize():

Callback Signature Description
onSuccess
required
(result: PayoutDropInSubmitResult) => voidThe callback fires after successful SDK payout submission.
onError
required
(error: BaseSdkException) => voidThe callback fires for configuration, empty-method, and payout failures delivered through the SDK error path.

PayoutDropInSubmitResult can include:

Field Description
systemTransactionIdThe Unity system transaction ID for a single-method payout.
merchantTransactionIdAn echo of your merchant transaction ID when present.
payoutMethodThe method used (e.g., Card or Paypal) when applicable.
payoutsThe 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.

Optional configuration

onGetShopper

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 fieldDescription
id
required
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.

Submit callbacks

These optional callbacks control pre-submit validation, loading UI, and analytics:

Callback Wired for Behaviour
onBeforeSubmit
  • Card
  • Apple Pay
  • Google Pay
The callback receives the PayoutMethod value. Return false (or a promise that resolves to false) to cancel submission.
onSubmit
  • Card
  • Apple Pay
  • Google Pay
The callback fires when card-on-file submit starts.
analyticsEventAllAn 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().

methodConfig

Payout-only instrument exclusion for the stored-instrument panels (card, Apple Pay, Google Pay, and PayPal).

Path Description
card.blacklistedInstrumentsgatewayTokenIds and schemeTokenIds arrays of token IDs to hide from the card list.
applePay.blacklistedInstrumentsThe same object shape as card: gatewayTokenIds and schemeTokenIds arrays of strings that identify Apple Pay device tokens to hide.
googlePay.blacklistedInstrumentsThe same object shape as card: gatewayTokenIds and schemeTokenIds arrays of strings that identify Google Pay device tokens to hide.
paypal.blacklistedPayerIdThe 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.

Localisation

Override merchant-facing strings under localisation.payoutDropIn:

KeyPurpose
cardLabel, paypalLabel, applePayLabel, googlePayLabelThe accordion method labels.
loadingTextThe text shown while create() loads configuration.
noPayoutMethodsErrorThe message when no methods remain.
containerAriaLabel, payoutMethodsGroupAriaLabelThe accessibility labels for the Drop-in root and method group.
payoutMethodExpandedAnnouncement, payoutMethodCollapsedAnnouncementThe screen reader announcements; use {method} as a placeholder.
cardOnFileTitle, cardOnFileLoadingAriaLabelThe card-on-file panel heading and loading label.
payoutNotSupportedForCardThe message shown when a Visa or Mastercard token is present but not selectable under gaming payout rules.
preferredMethodTitle, preferredMethodDescription, preferredMethodAmountLabel, preferredMethodGroupLabelCopy for the customer-driven preferred-method closed-loop screen.
mandatoryAllocationTitle, mandatoryAllocationDescription, mandatoryRemainingDescription, mandatorySelectPaymentMethodLabelCopy for the mandatory allocation closed-loop screen. mandatoryRemainingDescription supports {currency} and {amount} placeholders.
finalAllocationTitle, finalAllocationDescription, finalAllocationTotalLabel, finalAllocationExcessAmountLabel, finalAllocationExcessGroupLabel, finalAllocationPolicyMessage, finalAllocationPolicyLinkLabel, finalAllocationRejectedMessage, finalAllocationAcceptLabel, finalAllocationBackLabel, finalAllocationContinueLabelCopy for the final allocation and review closed-loop screens.

Closed-loop enforcement

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 onError for that fallback.
  • If allocation or closed-loop config retrieval throws, Drop-in calls onError (typically SDK0000) 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:

PropertyDescription
helpUrlA help or FAQ URL opened from the closed-loop policy banner.
hideInformationBannerWhen 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.

Inherited optional settings

These properties come from the shared Web SDK config surface. Most Payout Drop-in integrations leave them unset.

PropertyDescription
paypalConfigThe 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.
kountDisabledWhen false (default), Kount remains enabled on card-on-file submit where risk screening data is applied.
clientName, siteNameDisplay names forwarded to provider experiences that support them.
restrictionsA 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).

Backend-driven configuration

Many behaviours are controlled in the Unity Portal and Sessions API rather than in frontend code.

Payout method availability

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.cards to be present (including []). cardSchemes alone doesn't enable card.
  • Wallet methods need their wallet entry and an eligible stored instrument.

Branding and method order

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.

Complete configuration examples

Minimal configuration

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');

Full configuration

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');