Skip to content

Error handling

Handle payout component errors in the iOS SDK.

Overview

Payout components on iOS report errors through BaseSdkException, which exposes an errorCode (SDKXXXX) and an errorMessage. Configuration and wallet validation failures are thrown when you call pxpCheckout.create. Runtime failures during SDK-initiated payout execution are delivered through onError on the payout submission component.

When you pass onError into the PayoutSubmissionComponentConfig initialiser, the parameter type is Error. Cast it to BaseSdkException to read errorCode and errorMessage. If you assign config.onError after initialisation, the stored property already receives a BaseSdkException.

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 pxpCheckout.create. For example, a missing email or payer ID, invalid amount, or invalid currency.
SDK-initiated payout executionDelivered to onError on the payout submission component (typically as PayoutFailedException).

With proceedPayoutWithSdk set to false, only onClick runs. Use that callback to notify your backend so it can execute the payout. Create-time validation still throws from create.

Error codes

The following tables list payout-related codes from the iOS 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.
SDK0200Component name must not be empty.
SDK0202Component configuration is required for the component type.
SDK0500Network error.
SDK0501Validation error.

PayPal payout validation

These codes are thrown when you create the amount, receiver, or submission component.

Error codeDescription
SDK0803PayPal payout receiver is required (email or payer ID is missing, or the email is empty).
SDK0805Receiver type must be Email.
SDK0807Receiver type must be Email when the wallet is Paypal.
SDK0808Invalid email format for the receiver.
SDK0809PayPal payer ID is required (empty string after trim).
SDK0810Amount must be a valid number (not NaN or infinite).
SDK0811Amount must be a positive number greater than 0.
SDK0813Currency code must be a non-empty string.
SDK0814Currency code must be a 3-letter ISO 4217 currency code.
SDK0815Invalid currency code.
SDK0816Email exceeds the maximum length of 127 characters.
SDK0817PayPal payer ID exceeds the maximum length of 13 characters.
SDK0818PayPal payer ID contains invalid characters. Only alphanumeric characters (A-Z, a-z, 0-9) are allowed.

SDK0804, SDK0806, and SDK0812 are defined in the SDK but are not thrown by the current payout amount, receiver, or submission create paths. Prefer the codes in the table above when mapping customer-facing messages.

Payout execution failures

When an SDK-initiated payout fails at runtime, the submission component typically delivers a PayoutFailedException to onError. Its errorCode and errorMessage are the code and reason returned by the API (or a related transport code such as an HTTP status code), not a fixed payout validation code.

Example

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

do {
    let config = PayoutSubmissionComponentConfig(
        submitText: "Withdraw with",
        onPrePayoutSubmit: {
            return PrePayoutSubmitResult(isApproved: true)
        },
        onError: { error in
            guard let error = error as? BaseSdkException else { return }
            print("Payout error: \(error.errorCode) - \(error.errorMessage)")
            showErrorDialog(error.errorMessage)
        }
    )
    let component = try pxpCheckout.create(.payoutSubmission, componentConfig: config)
} catch let error as BaseSdkException {
    print("Create failed: \(error.errorCode) - \(error.errorMessage)")
    showErrorDialog(error.errorMessage)
} catch {
    print("Create failed: \(error.localizedDescription)")
}