Skip to content

Troubleshooting

Diagnose and fix common Payout Drop-in integration issues.

Overview

Most production issues fall into four categories:

  • Session or site configuration: Wrong service, environment, or funding types (SDK1700, SDK1701).
  • Shopper context: Missing or wrong shopper ID; instruments not loaded.
  • Instrument eligibility: No tokens, expired tokens, blacklists, inactive PayPal link.
  • Submission failures: Provider or payout API errors (SDK1703).

Use browser DevTools network tabs to inspect session-scoped SDK calls. Correlate merchantTransactionId with your backend logs. Never log hmacKey, inbound API tokens, or full wallet JWTs in client logs.

Quick diagnostics

Start with these checks when Drop-in misbehaves:

import { PayoutDropIn } from '@pxpio/web-components-sdk';

function diagnosePayoutDropIn(sessionData: any, config: any) {
  console.group('Payout Drop-in diagnostics');

  console.log('SDK imported:', typeof PayoutDropIn !== 'undefined');

  const container = document.getElementById('payout-drop-in-container');
  console.log('Container exists:', !!container);
  console.log('Container visible:', container ? container.offsetParent !== null : false);

  console.log('Session ID:', sessionData?.sessionId ? 'Present' : 'Missing');
  console.log('HMAC key:', sessionData?.hmacKey ? 'Present' : 'Missing');
  console.log('Allowed funding types:', sessionData?.allowedFundingTypes);
  console.log('Cards field present:', sessionData?.allowedFundingTypes?.cards != null);
  console.log('Environment:', config?.environment);
  console.log('Owner ID:', config?.ownerId);
  console.log('Protocol:', location.protocol);

  console.groupEnd();
}

Card requires allowedFundingTypes.cards to be present on the session (including an empty array). cardSchemes alone doesn't enable card.

Common issues

No payout methods are shown

Symptoms: The container loads (or shows loading then an empty UI), but no withdrawal method appears.

Common causes and fixes:

CauseSolution
Session doesn't allow card, PayPal, Apple Pay, or Google PayCheck allowedFundingTypes. For card, ensure cards is present.
onGetShopper missing or returns an empty IDRequire authentication and return a real shopper ID so tokens and PayPal can load.
Shopper has no eligible stored instrumentsVault plain cards, link PayPal, or store Apple Pay or Google Pay device tokens for the test shopper.
All instruments excluded by methodConfig blacklistsTemporarily remove blacklists to isolate filtering.
Token or PayPal lookup failed silentlyMethods can hide without onError. Inspect network calls for active tokens and wallet associations.
Site configuration missing or wrong environmentExpect SDK1700. Enable Payout Drop-in and match test or live to the site.

How to identify:

  1. Check onError for SDK1700 or SDK1701.
  2. Inspect session JSON: allowedFundingTypes.
  3. Confirm the shopper ID matches vault records.
  4. Call the token vault API from your backend with the same ownerId and shopper ID.
  5. Review PayPal wallet association for an active PayPal recipient.
  6. Temporarily remove blacklists.

See How it works and the method guides: Card, PayPal, Apple Pay, Google Pay.

Configuration not found (SDK1700)

Symptoms: Error mentions failed payout Drop-in configuration retrieval; container may show an error shell.

Common causes and fixes:

CauseSolution
Payout Drop-in not enabled for the siteActivate the Payout Drop-in service for the site. See Activation.
Wrong environmentMatch environment: 'test' or 'live' to the site and credentials.
Invalid or expired sessionId or hmacKeyCreate a fresh payout session and retry create().
Network failure calling configurationsCheck the network tab for non-2xx on api/v1/payout-dropin/configurations.

No payout methods for session (SDK1701)

Symptoms: Explicit error that no payout methods are available after mount.

Common causes and fixes:

CauseSolution
Session allows methods but every method fails instrument resolutionUse the same fixes as No payout methods are shown.
Card allowed but no plain-card tokensVault non-device plain-card tokens for the shopper.
Wallets allowed but no matching device tokensVault Apple Pay or Google Pay tokens with panType: Device.
PayPal allowed but association inactive or missingComplete linking; confirm activeStatus: Active and recipientWallet: Paypal.
All remaining methods blacklistedAdjust methodConfig blacklists.

Treat SDK1701 as expected when deliberately testing an empty vault.

The PayPal method is missing

Symptoms: PayPal is enabled on the session, but the accordion has no PayPal entry.

Common causes and fixes:

CauseSolution
allowedFundingTypes.wallets.paypal absentEnable PayPal on the payout session.
No shopper IDImplement onGetShopper with the authenticated shopper ID.
Association missing, inactive, or wrong recipient walletLink PayPal for the shopper; confirm Active and Paypal.
methodConfig.paypal.blacklistedPayerId matches the linked payerRemove or correct the blacklist.
Lookup failedPayPal is hidden without necessarily calling onError. Retry with a known-good association.

Don't log the raw wallet-association JWT in production. See PayPal.

Card, Apple Pay, or Google Pay missing while PayPal works

Symptoms: PayPal renders, but card-on-file methods don't.

Common causes and fixes:

CauseSolution
Card funding not present on the sessionInclude allowedFundingTypes.cards.
No matching device tokens for Apple Pay or Google PayVault tokens with walletType: ApplePay or GooglePay and panType: Device.
Tokens already expiredExpired tokens are filtered out of the list. Re-vault a valid instrument. For tokens still in date, shoppers can edit expiry in the list UI where allowed.
Wrong instrument type for the methodPlain cards appear under card. Device wallet tokens appear under Apple Pay or Google Pay only.
Blacklists hide the only remaining tokensCheck methodConfig.card, applePay, or googlePay blacklists.

Payout submission fails (SDK1703)

Symptoms: Shopper submits; onError runs instead of onSuccess.

Common causes and fixes:

CauseSolution
Instrument no longer valid at the providerAsk the shopper to choose another method, or re-link or re-vault.
Payout API business rule, such as example limits or destination eligibilityFix eligibility on the server before retrying.
Amount or currency mismatch vs sessionAlign session creation and transactionData.
Provider temporary outageOffer retry after checking backend state.

How to identify: Log ErrorCode, name, message, and details. Search your backend by merchantTransactionId. Both card-on-file failure and PayPal initiation failure can use SDK1703: don't branch on the code alone.

Before encouraging another attempt, confirm no successful payout already exists for that merchantTransactionId. See Error handling.

Authentication or authorisation failure on card-on-file submit

Symptoms: Card, Apple Pay, or Google Pay submit fails with SDK1114 or SDK1115.

These codes are uncommon on the standard Payout Drop-in path. Payout intent skips the Unity 3-D Secure authentication flow, so shoppers typically won't see them during stored-instrument withdrawals. If they do appear:

CodeTypical meaningWhat to try
SDK1114Authentication failed or authentication context was missing.Ask the shopper to retry or choose another method.
SDK1115Authorisation evaluation didn't allow the payout to proceed.Retry later or offer another method; verify backend state first.

Session or initialisation errors

Symptoms: initialize() throws, or create() rejects before the UI renders.

Common causes and fixes:

CauseSolution
Missing required config (environment, session, transaction data, onSuccess, onError)Validate the config object before calling initialize().
Missing sessionId or hmacKeyFix the session payload from your backend (SDK0103 or SDK0104 style throws).
onGetShopper rejectscreate() rejects without calling onError: show a login prompt.
Container ID mismatch or element not in the DOMEnsure the element exists before create(); IDs are case-sensitive.

Wrap both initialize() and create() in try or catch.

Duplicate UI after navigation

Symptoms: Multiple accordions or repeated handlers after route changes.

Cause: create() called again without destroy().

Solution: In SPA frameworks, call destroy() in useEffect cleanup or on route leave before remounting.

Debugging checklist

Work through these checks before escalating:

CheckAction
Session serviceTypeMust be PayoutDropIn when creating the session.
Session intentsUse Payout for enabled methods.
Amount and currencyMatch the backend session and frontend transactionData.
Shopper IDFrom your authenticated session via onGetShopper.
ownerIdThe merchant group ID used for the token vault.
Environmenttest or live, consistent with credentials and site.
Card fundingallowedFundingTypes.cards present when Card should appear.
NetworkConfigurations, active-tokens, and PayPal wallet-association calls.
ErrorsLook for SDK1700, SDK1701, SDK1703, uncommon SDK1114 or SDK1115, and mount exceptions.