Skip to content

Error handling

Understand Payout Drop-in error types, handle withdrawal failures, and recover safely.

Overview

Payout Drop-in delivers most runtime failures through the required onError callback. Configuration retrieval problems, empty method sets, card-on-file submit failures, and PayPal payout initiation failures route through this path.

Errors extend BaseSdkException and expose a stable ErrorCode you can branch on, plus a human-readable message. Some payout initiation failures also populate details with the merchant error payload from the payout API.

Not every failure uses onError:

  • Synchronous validation when calling PayoutDropIn.initialize() throws immediately.
  • A rejected onGetShopper promise causes create() to reject.
  • Some instrument lookups fail quietly by hiding a method instead of raising onError.

Always wrap initialize() and create() in try or catch, and treat onSuccess as submission acknowledgement only. Confirm final payout state on your backend before updating the shopper's withdrawal status.

When onError runs during create() (e.g., SDK1700 or SDK1701), create() usually settles without throwing. Rely on onError for those cases, and use try or catch for rejections such as a failed onGetShopper.

Error callback

All runtime SDK errors are delivered through onError:

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

const payoutDropIn = PayoutDropIn.initialize({
  // ... other config
  onError: (error: BaseSdkException) => {
    console.error('Payout Drop-in error:', {
      errorCode: error.ErrorCode,
      message: error.message,
      name: error.name,
      details: error.details,
    });

    showErrorMessage(mapToCustomerSafeMessage(error));
  },
});

try {
  await payoutDropIn.create('payout-drop-in-container');
} catch (error) {
  console.error('Mount failed:', error);
  showErrorMessage(
    'We could not load withdrawal options. Please refresh or sign in again.'
  );
}

Error object structure

Each BaseSdkException exposes these fields:

Property Description
message
string
required
A human-readable description of what went wrong.
ErrorCode
string
required
The SDK error code in the form SDK#### (e.g., 'SDK1700', 'SDK1703'). Use this for programmatic handling.
name
string
The exception class name (e.g., 'PayoutDropInConfigNotFoundSdkException' or 'PayoutInitiationFailedException').
details
unknown
A structured payload on some payout initiation failures. Often the merchant error response, including fields such as errorReason, errorCode, correlationId, state, stateData, merchantTransactionId, and systemTransactionId when the API returned them.

Use error.ErrorCode for branching. There's no separate code property on BaseSdkException.

Error categories

Errors fall into several groups based on when they occur and how you should respond.

Configuration and mount errors

These occur while Drop-in loads site configuration or mounts into the container:

ExceptionError codeDescriptionSolution
PayoutDropInConfigNotFoundSdkExceptionSDK1700Failed to retrieve Payout Drop-in configuration, or the configuration response was empty.Confirm Payout Drop-in is enabled for the site, environment matches the session, and the configurations request succeeds in the network tab.
UnexpectedSdkExceptionSDK0000An unexpected failure during mount. For example, closed-loop allocation setup failing when closed-loop enforcement is active.Log the full error, check Unity and network logs, and retry with a fresh session after addressing the underlying fault.
MissingConfigException, MissingConfigEnvironmentException, MissingConfigSessionException, MissingConfigSessionIdException, or MissingConfigSessionHmackeyExceptionSDK0100 to SDK0104Required initialisation fields are missing. These throw synchronously from initialize(). They don't call onError.Fix the config object your backend supplies before calling initialize() again.

The following example maps mount-time configuration failures to shopper-safe messages:

onError: (error: BaseSdkException) => {
  if (error.ErrorCode === 'SDK1700') {
    showErrorMessage(
      'We could not load withdrawal settings. Please refresh the page or try again later.'
    );
    return;
  }

  if (error.ErrorCode === 'SDK0000') {
    showErrorMessage(
      'Something went wrong while loading withdrawals. Please try again.'
    );
    return;
  }
};

Availability errors

Drop-in raises these when it mounts successfully but no withdrawal methods remain after session funding checks, instrument resolution, and blacklists:

ExceptionError codeDescriptionSolution
NoPayoutMethodsAvailableExceptionSDK1701No payout methods are available for this session.Check allowedFundingTypes, the shopper ID from onGetShopper, stored instruments, PayPal association status, and methodConfig blacklists. See Troubleshooting.

SDK1701 commonly means one of the following:

  • The session allows methods, but the shopper has no eligible stored instruments.
  • Card-on-file methods were filtered out because no matching tokens remained.
  • PayPal was allowed but no active linked account was found.
  • Blacklists removed every remaining instrument or payer.

When a single method has no instruments, Drop-in usually hides that method. Drop-in raises SDK1701 when the filtered set becomes empty.

Payout submission errors

These errors occur while initiating a withdrawal for card, Apple Pay, Google Pay, or PayPal:

ExceptionError codeDescriptionUser action
PayoutDropInCardPayoutFailedSdkExceptionSDK1703Card-on-file submit failed, or a closed-loop enforcement submit failed. Message is typically Card payout failed. Closed-loop can use this exception even when more than one instrument was involved.Inspect message and any details. Offer retry or another method after checking backend state.
PayoutInitiationFailedExceptionSDK1703Payout API returned a merchant error (card-on-file failed submit result, or PayPal panel error). Message is Payout initiation failed: {reason}.Read message and details. Map provider reasons to shopper-safe copy, and correlate with your withdrawal record.
PayoutCardOnFileBundleRequiredExceptionSDK1702Card-on-file panel expected a token bundle that wasn't provided.Ensure create() completed normally. If this appears in production, upgrade the SDK and contact support with logs.

Both card payout failure and general payout initiation failure use SDK1703. Closed-loop enforcement failures can also surface as PayoutDropInCardPayoutFailedSdkException with the same code. Don't branch business logic on the code alone. Distinguish by name, message, and details, and always confirm transaction state on your backend before allowing another attempt.

For PayoutInitiationFailedException, details is the merchant error object. The SDK builds message from, in order: errorReason, then stateData.message, then stateData.code, then errorCode.

Authentication and authorisation errors

Card-on-file submit wires authentication and authorisation evaluation callbacks. Payout intent skips the Unity 3D Secure authentication flow, so these codes are uncommon on the standard stored-instrument path. If they do appear, you may see the following:

ExceptionError codeDescriptionUser action
CheckoutDropInAuthenticationFailedSdkExceptionSDK1114Authentication failed, or authentication context was missing when authorisation was about to proceed.Ask the shopper to try again, or choose another method.
CheckoutDropInAuthorisationFailedSdkExceptionSDK1115Authorisation evaluation didn't allow the payout to proceed.Ask the shopper to try again later, or choose another method.

Prefer checking ErrorCode first, then message for nuance. Treat these codes as uncommon on the standard payout stored-instrument path.

Validation and network errors

Use these codes and message checks for validation and connectivity problems:

Exception or detectionError codeDescriptionUser action
ValidationExceptionSDK0501Submit-path validation failure forwarded through card-on-file error handling.Correct invalid input if your UI collects any, then retry.
Network errorSDK0500Network failure reported by the SDK.Check connectivity and retry.
Message-basedNoneThe message contains session or expired.Recreate the payout session and refresh the page.
Message-basedNoneThe message contains timeout or unavailable.Retry shortly and show a retry control.

Failures that hide a method instead of calling onError

These don't always raise onError:

ScenarioSDK behaviourWhat you should do
Card token lookup fails or returns no usable tokens.Card, Apple Pay, or Google Pay may be omitted from the accordion.Confirm vault data for the shopper. Expect SDK1701 only if every method is removed.
PayPal account lookup fails, or is inactive or blacklisted.PayPal is hidden and Drop-in continues with remaining methods.Check wallet association and methodConfig.paypal.blacklistedPayerId.
onGetShopper is rejected.create() rejects. onError isn't used for that rejection.Catch the rejection, re-authenticate, and call create() again.

Message-based detection for SDK1703

Provider and payout API messages vary. After checking ErrorCode === 'SDK1703', inspect message (and details when present):

ScenarioDetection approachUser guidance
DeclinedThe message contains declined.Try another method, or contact the card issuer or PayPal.
Insufficient fundsThe message contains insufficient.Choose another destination or reduce the amount if your product allows it.
Duplicate transactionThe message or details.stateData mentions a duplicate merchant transaction ID.Don't resubmit the same merchantTransactionId. Check backend status first.
Generic initiation failureThe message starts with Payout initiation failed:.Show a safe generic withdrawal failure message and verify backend state.

The following example inspects SDK1703 messages for common decline patterns:

onError: (error: BaseSdkException) => {
  if (error.ErrorCode === 'SDK1703') {
    const text = error.message.toLowerCase();

    if (text.includes('declined')) {
      showErrorMessage(
        'This withdrawal was declined. Please try another method or contact your provider.'
      );
      return;
    }

    if (text.includes('insufficient')) {
      showErrorMessage(
        'There are insufficient funds on the selected destination. Please choose another method.'
      );
      return;
    }

    showErrorMessage(
      "Your withdrawal could not be completed. Please try again or contact support."
    );
    return;
  }
};

Error handling patterns

Basic handling

Log for support, show a safe shopper message, and clear loading state:

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

onError: (error: BaseSdkException) => {
  console.error('Payout error:', {
    errorCode: error.ErrorCode,
    message: error.message,
    name: error.name,
  });

  hideLoadingOverlay();

  if (error.ErrorCode === 'SDK1701') {
    showErrorMessage('No withdrawal methods are available right now.');
    return;
  }

  if (error.ErrorCode === 'SDK1700') {
    showErrorMessage(
      "We couldn't load withdrawal settings. Please refresh or try again later."
    );
    return;
  }

  showErrorMessage(
    "Your withdrawal could not be completed. Please try again or contact support."
  );
};

Handling with recovery

Add monitoring, limited retries for transient faults, and alternative-method prompts for submission declines:

let retryCount = 0;
const MAX_RETRIES = 3;

onError: (error: BaseSdkException) => {
  logErrorToMonitoring({
    category: 'payout_error',
    errorCode: error.ErrorCode,
    message: error.message,
    exception: error.name,
    merchantTransactionId: currentWithdrawalId,
    sessionId: sessionData.sessionId,
  });

  analytics.track('payout_failed', {
    errorCode: error.ErrorCode,
    retryCount,
  });

  hideLoadingOverlay();

  const isRetryable =
    error.ErrorCode === 'SDK0500' ||
    error.message.toLowerCase().includes('timeout') ||
    error.message.toLowerCase().includes('unavailable');

  if (isRetryable && retryCount < MAX_RETRIES) {
    retryCount += 1;
    showWarningMessage(
      `Connection issue (attempt ${retryCount}/${MAX_RETRIES}). Please try again.`
    );
    showRetryButton();
    return;
  }

  retryCount = 0;

  if (error.ErrorCode === 'SDK1701') {
    showErrorMessage('No withdrawal methods are available right now.');
    return;
  }

  if (error.ErrorCode === 'SDK1114' || error.ErrorCode === 'SDK1115') {
    showErrorMessage(
      "We couldn't authenticate this withdrawal. Please try again or use a different method."
    );
    return;
  }

  if (error.ErrorCode === 'SDK1703') {
    showErrorMessage(
      "Your withdrawal could not be completed. Please try again or choose another method."
    );
    offerAlternativeMethods();
    return;
  }

  if (
    error.message.toLowerCase().includes('session') ||
    error.message.toLowerCase().includes('expired')
  ) {
    showErrorMessage('Your session has expired. Please refresh the page.');
    showRefreshButton();
    return;
  }

  showErrorMessage(
    "Your withdrawal could not be completed. Please try again or contact support."
  );
};

Never mark a withdrawal as paid because the shopper retried after an error. Confirm status with your webhook handler or a server-side transaction lookup first. A failed client callback doesn't prove that no payout was created.

Logging checklist

Log the following for support engineers:

  • ErrorCode, name, and message
  • Your merchantTransactionId
  • sessionId (never log hmacKey)
  • Useful fields from details such as correlationId, systemTransactionId, and stateData

Don't log inbound API tokens, encryption keys, wallet JWTs, or full card tokens in client logs.

Recovery summary

Map each common code to a recovery action:

ErrorRecovery
SDK1700Fix site and environment configuration. Recreate the session, then retry create().
SDK1701Explain that no methods are available. Prompt linking a card or PayPal, or contact support.
SDK1703Allow retry only after backend shows no successful transaction for that merchantTransactionId.
SDK1114 or SDK1115Uncommon on the standard payout path. If they appear, offer retry or another method. Don't assume the payout was created.
SDK0500 or timeoutShow retry with a small attempt limit.
Mount or onGetShopper failureRe-authenticate the shopper. Recreate the payout session, then call create() again.