Diagnose and fix common Payout Drop-in integration issues.
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.
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.
Symptoms: The container loads (or shows loading then an empty UI), but no withdrawal method appears.
Common causes and fixes:
| Cause | Solution |
|---|---|
| Session doesn't allow card, PayPal, Apple Pay, or Google Pay | Check allowedFundingTypes. For card, ensure cards is present. |
onGetShopper missing or returns an empty ID | Require authentication and return a real shopper ID so tokens and PayPal can load. |
| Shopper has no eligible stored instruments | Vault plain cards, link PayPal, or store Apple Pay or Google Pay device tokens for the test shopper. |
All instruments excluded by methodConfig blacklists | Temporarily remove blacklists to isolate filtering. |
| Token or PayPal lookup failed silently | Methods can hide without onError. Inspect network calls for active tokens and wallet associations. |
| Site configuration missing or wrong environment | Expect SDK1700. Enable Payout Drop-in and match test or live to the site. |
How to identify:
- Check
onErrorforSDK1700orSDK1701. - Inspect session JSON:
allowedFundingTypes. - Confirm the shopper ID matches vault records.
- Call the token vault API from your backend with the same
ownerIdand shopper ID. - Review PayPal wallet association for an active PayPal recipient.
- Temporarily remove blacklists.
See How it works and the method guides: Card, PayPal, Apple Pay, Google Pay.
Symptoms: Error mentions failed payout Drop-in configuration retrieval; container may show an error shell.
Common causes and fixes:
| Cause | Solution |
|---|---|
| Payout Drop-in not enabled for the site | Activate the Payout Drop-in service for the site. See Activation. |
| Wrong environment | Match environment: 'test' or 'live' to the site and credentials. |
Invalid or expired sessionId or hmacKey | Create a fresh payout session and retry create(). |
| Network failure calling configurations | Check the network tab for non-2xx on api/v1/payout-dropin/configurations. |
Symptoms: Explicit error that no payout methods are available after mount.
Common causes and fixes:
| Cause | Solution |
|---|---|
| Session allows methods but every method fails instrument resolution | Use the same fixes as No payout methods are shown. |
| Card allowed but no plain-card tokens | Vault non-device plain-card tokens for the shopper. |
| Wallets allowed but no matching device tokens | Vault Apple Pay or Google Pay tokens with panType: Device. |
| PayPal allowed but association inactive or missing | Complete linking; confirm activeStatus: Active and recipientWallet: Paypal. |
| All remaining methods blacklisted | Adjust methodConfig blacklists. |
Treat SDK1701 as expected when deliberately testing an empty vault.
Symptoms: PayPal is enabled on the session, but the accordion has no PayPal entry.
Common causes and fixes:
| Cause | Solution |
|---|---|
allowedFundingTypes.wallets.paypal absent | Enable PayPal on the payout session. |
| No shopper ID | Implement onGetShopper with the authenticated shopper ID. |
| Association missing, inactive, or wrong recipient wallet | Link PayPal for the shopper; confirm Active and Paypal. |
methodConfig.paypal.blacklistedPayerId matches the linked payer | Remove or correct the blacklist. |
| Lookup failed | PayPal is hidden without necessarily calling onError. Retry with a known-good association. |
Don't log the raw wallet-association JWT in production. See PayPal.
Symptoms: PayPal renders, but card-on-file methods don't.
Common causes and fixes:
| Cause | Solution |
|---|---|
| Card funding not present on the session | Include allowedFundingTypes.cards. |
| No matching device tokens for Apple Pay or Google Pay | Vault tokens with walletType: ApplePay or GooglePay and panType: Device. |
| Tokens already expired | Expired 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 method | Plain cards appear under card. Device wallet tokens appear under Apple Pay or Google Pay only. |
| Blacklists hide the only remaining tokens | Check methodConfig.card, applePay, or googlePay blacklists. |
Symptoms: Shopper submits; onError runs instead of onSuccess.
Common causes and fixes:
| Cause | Solution |
|---|---|
| Instrument no longer valid at the provider | Ask the shopper to choose another method, or re-link or re-vault. |
| Payout API business rule, such as example limits or destination eligibility | Fix eligibility on the server before retrying. |
| Amount or currency mismatch vs session | Align session creation and transactionData. |
| Provider temporary outage | Offer 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.
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:
| Code | Typical meaning | What to try |
|---|---|---|
SDK1114 | Authentication failed or authentication context was missing. | Ask the shopper to retry or choose another method. |
SDK1115 | Authorisation evaluation didn't allow the payout to proceed. | Retry later or offer another method; verify backend state first. |
Symptoms: initialize() throws, or create() rejects before the UI renders.
Common causes and fixes:
| Cause | Solution |
|---|---|
Missing required config (environment, session, transaction data, onSuccess, onError) | Validate the config object before calling initialize(). |
Missing sessionId or hmacKey | Fix the session payload from your backend (SDK0103 or SDK0104 style throws). |
onGetShopper rejects | create() rejects without calling onError: show a login prompt. |
| Container ID mismatch or element not in the DOM | Ensure the element exists before create(); IDs are case-sensitive. |
Wrap both initialize() and create() in try or catch.
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.
Work through these checks before escalating:
| Check | Action |
|---|---|
Session serviceType | Must be PayoutDropIn when creating the session. |
| Session intents | Use Payout for enabled methods. |
| Amount and currency | Match the backend session and frontend transactionData. |
| Shopper ID | From your authenticated session via onGetShopper. |
ownerId | The merchant group ID used for the token vault. |
| Environment | test or live, consistent with credentials and site. |
| Card funding | allowedFundingTypes.cards present when Card should appear. |
| Network | Configurations, active-tokens, and PayPal wallet-association calls. |
| Errors | Look for SDK1700, SDK1701, SDK1703, uncommon SDK1114 or SDK1115, and mount exceptions. |