Understand Payout Drop-in error types, handle withdrawal failures, and recover safely.
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
onGetShopperpromise causescreate()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.
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.'
);
}Each BaseSdkException exposes these fields:
| Property | Description |
|---|---|
messagestring required | A human-readable description of what went wrong. |
ErrorCodestring required | The SDK error code in the form SDK#### (e.g., 'SDK1700', 'SDK1703'). Use this for programmatic handling. |
namestring | The exception class name (e.g., 'PayoutDropInConfigNotFoundSdkException' or 'PayoutInitiationFailedException'). |
detailsunknown | 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.
Errors fall into several groups based on when they occur and how you should respond.
These occur while Drop-in loads site configuration or mounts into the container:
| Exception | Error code | Description | Solution |
|---|---|---|---|
PayoutDropInConfigNotFoundSdkException | SDK1700 | Failed 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. |
UnexpectedSdkException | SDK0000 | An 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 MissingConfigSessionHmackeyException | SDK0100 to SDK0104 | Required 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;
}
};Drop-in raises these when it mounts successfully but no withdrawal methods remain after session funding checks, instrument resolution, and blacklists:
| Exception | Error code | Description | Solution |
|---|---|---|---|
NoPayoutMethodsAvailableException | SDK1701 | No 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.
These errors occur while initiating a withdrawal for card, Apple Pay, Google Pay, or PayPal:
| Exception | Error code | Description | User action |
|---|---|---|---|
PayoutDropInCardPayoutFailedSdkException | SDK1703 | Card-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. |
PayoutInitiationFailedException | SDK1703 | Payout 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. |
PayoutCardOnFileBundleRequiredException | SDK1702 | Card-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.
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:
| Exception | Error code | Description | User action |
|---|---|---|---|
CheckoutDropInAuthenticationFailedSdkException | SDK1114 | Authentication failed, or authentication context was missing when authorisation was about to proceed. | Ask the shopper to try again, or choose another method. |
CheckoutDropInAuthorisationFailedSdkException | SDK1115 | Authorisation 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.
Use these codes and message checks for validation and connectivity problems:
| Exception or detection | Error code | Description | User action |
|---|---|---|---|
ValidationException | SDK0501 | Submit-path validation failure forwarded through card-on-file error handling. | Correct invalid input if your UI collects any, then retry. |
| Network error | SDK0500 | Network failure reported by the SDK. | Check connectivity and retry. |
| Message-based | None | The message contains session or expired. | Recreate the payout session and refresh the page. |
| Message-based | None | The message contains timeout or unavailable. | Retry shortly and show a retry control. |
These don't always raise onError:
| Scenario | SDK behaviour | What 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. |
Provider and payout API messages vary. After checking ErrorCode === 'SDK1703', inspect message (and details when present):
| Scenario | Detection approach | User guidance |
|---|---|---|
| Declined | The message contains declined. | Try another method, or contact the card issuer or PayPal. |
| Insufficient funds | The message contains insufficient. | Choose another destination or reduce the amount if your product allows it. |
| Duplicate transaction | The message or details.stateData mentions a duplicate merchant transaction ID. | Don't resubmit the same merchantTransactionId. Check backend status first. |
| Generic initiation failure | The 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;
}
};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."
);
};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.
Log the following for support engineers:
ErrorCode,name, andmessage- Your
merchantTransactionId sessionId(never loghmacKey)- Useful fields from
detailssuch ascorrelationId,systemTransactionId, andstateData
Don't log inbound API tokens, encryption keys, wallet JWTs, or full card tokens in client logs.
Map each common code to a recovery action:
| Error | Recovery |
|---|---|
SDK1700 | Fix site and environment configuration. Recreate the session, then retry create(). |
SDK1701 | Explain that no methods are available. Prompt linking a card or PayPal, or contact support. |
SDK1703 | Allow retry only after backend shows no successful transaction for that merchantTransactionId. |
SDK1114 or SDK1115 | Uncommon on the standard payout path. If they appear, offer retry or another method. Don't assume the payout was created. |
SDK0500 or timeout | Show retry with a small attempt limit. |
Mount or onGetShopper failure | Re-authenticate the shopper. Recreate the payout session, then call create() again. |