Skip to content

Error handling

Handle payout component errors in the Web SDK.

Overview

Payout components on Web report errors as an error code (SDKXXXX) and a descriptive message. Configuration and wallet validation failures are thrown when you create a component. Runtime failures during SDK-initiated payout execution are delivered through onError.

Catch create-time errors around create. Use onError on the submission component for failures after the customer submits a payout. For field-level rules and examples, see Data validation.

When errors are raised

The following table summarises where payout errors appear.

StageHow you receive the error
Component creationThrown from create. For example, missing wallet fields, invalid amount, or invalid currency.
SDK-initiated payout executionDelivered to onError on the payout submission component.

Error codes

The following tables list payout-related codes from the Web SDK.

Common and SDK configuration

Error codeDescription
SDK0000Unexpected error.
SDK0001Not implemented.
SDK0100Missing SDK config.
SDK0101Missing SDK config: environment.
SDK0102Missing SDK config: session data.
SDK0103Missing SDK config: session ID.
SDK0104Missing SDK config: session HMAC key.
SDK0106Intent type does not support the requested component.
SDK0108PayPal is missing from allowed funding types.
SDK0112PayPal intent type is required for the component but was not provided.
SDK0200Component name must not be empty.
SDK0201Container element with the given ID was not found.
SDK0500Network error.
SDK0501Validation error.

PayPal payout validation

Error codeDescription
SDK0803Receiver value is required.
SDK0804Invalid receiver type. Valid values are Email, Phone, PaypalId, and UserHandle.
SDK0805Receiver type must be Email.
SDK0806Invalid wallet value. Must be Paypal.
SDK0807Receiver type must be Email when the wallet is Paypal.
SDK0808Invalid email format for the receiver.
SDK0809PayPal payer ID is required.
SDK0810Amount must be a valid number.
SDK0811Amount must be a positive number greater than 0.
SDK0812Amount is required.
SDK0813Currency code must be a non-empty string.
SDK0814Currency code must be a 3-letter ISO 4217 currency code.
SDK0815Invalid currency code.
SDK0816Receiver type is required.
SDK0818A PayPal payout field exceeds its maximum length.

Venmo payout validation

Error codeDescription
SDK0900Venmo wallet is required.
SDK0901Receiver value is required for Venmo.
SDK0902Venmo recipient type is required.
SDK0903Invalid Venmo recipient type. Valid values are Email, Phone, and UserHandle.
SDK0904Invalid phone format for the Venmo receiver. Use numeric characters only.
SDK0905Venmo only supports USD currency.

Payout submission configuration

Error codeDescription
SDK1000PayPal configuration is required.
SDK1001Recipient wallet is required.
SDK1002Receiver and recipient type are required.
SDK1003Unsupported recipient wallet. Valid values are Paypal and Venmo.

Notes longer than 4000 characters are truncated with a console warning. The submission path does not throw SDK1004 for an over-long note. The note field is included with Venmo payouts only.

Example

The following example catches create-time errors and handles runtime failures in onError:

try {
  const submitComponent = pxpCheckoutSdk.create("payout-submission", {
    recipientWallet: "Paypal",
    onError: (error) => {
      console.error("Payout error:", error.ErrorCode, error.message);
      showErrorMessage(error.message);
    },
  });
} catch (error) {
  console.error("Create failed:", error.ErrorCode, error.message);
  showErrorMessage(error.message);
}