Handle payout component errors in the iOS SDK.
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.
The following table summarises where payout errors appear.
| Stage | How you receive the error |
|---|---|
| Component creation | Thrown from pxpCheckout.create. For example, a missing email or payer ID, invalid amount, or invalid currency. |
| SDK-initiated payout execution | Delivered 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.
The following tables list payout-related codes from the iOS SDK.
| Error code | Description |
|---|---|
SDK0000 | Unexpected error. |
SDK0001 | Not implemented. |
SDK0100 | Missing SDK config. |
SDK0101 | Missing SDK config: environment. |
SDK0102 | Missing SDK config: session data. |
SDK0103 | Missing SDK config: session ID. |
SDK0104 | Missing SDK config: session HMAC key. |
SDK0106 | Intent type does not support the requested component. |
SDK0200 | Component name must not be empty. |
SDK0202 | Component configuration is required for the component type. |
SDK0500 | Network error. |
SDK0501 | Validation error. |
These codes are thrown when you create the amount, receiver, or submission component.
| Error code | Description |
|---|---|
SDK0803 | PayPal payout receiver is required (email or payer ID is missing, or the email is empty). |
SDK0805 | Receiver type must be Email. |
SDK0807 | Receiver type must be Email when the wallet is Paypal. |
SDK0808 | Invalid email format for the receiver. |
SDK0809 | PayPal payer ID is required (empty string after trim). |
SDK0810 | Amount must be a valid number (not NaN or infinite). |
SDK0811 | Amount must be a positive number greater than 0. |
SDK0813 | Currency code must be a non-empty string. |
SDK0814 | Currency code must be a 3-letter ISO 4217 currency code. |
SDK0815 | Invalid currency code. |
SDK0816 | Email exceeds the maximum length of 127 characters. |
SDK0817 | PayPal payer ID exceeds the maximum length of 13 characters. |
SDK0818 | PayPal 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.
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.
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)")
}