Skip to content

Error handling

Handle payout component errors in the Android SDK.

Overview

Payout components on Android report validation and execution failures with payout-specific codes in the PO0x range, plus related OAuth codes in the OA0x range when you use an OAuth submission flow. Submission failures are delivered to onError as a PayOutError, which exposes errorCode and errorReason.

Validate wallet and transaction data early, catch failures when you create or submit components, and map codes to clear customer-facing messages. 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
SDK initialisation and component validationThrown as validation errors. For example an invalid amount, currency, email, or payer ID.
Payout submissionDelivered through the submission component onError callback as a PayOutError.

With proceedPayoutWithSdk set to false, the SDK calls onClick (if configured) and returns without validating or executing the payout. Use that callback to notify your backend so it can execute the payout. Create-time validation still throws when you create components. With proceedPayoutWithSdk set to true, if onPrePayoutSubmit is missing or returns isApproved = false, the SDK cancels the payout and does not call onError. Handle that case in your approval UI.

Error codes

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

Payout validation and execution

Error codeDescription
PO01General payout error.
PO02Transaction amount should be greater than 0.
PO03Invalid currency code.
PO04Invalid recipient data. This code covers several receiver and wallet failures, including an empty receiver, missing payer ID, invalid email format, email or payer ID length limits, unsupported recipient type, and unsupported recipient wallet. Only Paypal is supported as the recipient wallet.
PO07Invalid or missing merchant transaction date. Use the ISO 8601 format (e.g., 2025-10-28T10:00:00Z).

Amount and currency display components may also surface string codes such as AMOUNT_MUST_BE_POSITIVE, INVALID_NUMERIC, or INVALID_CURRENCY during local validation. Treat those as validation failures and correct transactionData before submission.

If you use the PayPal OAuth submission flow, the SDK may also report the following codes.

Error codeDescription
OA01General OAuth error.
OA02Invalid OAuth state.
OA03Invalid OAuth authorisation code.
OA04OAuth timeout.

Example

The following example maps common payout codes from a PayOutError to customer-facing messages:

fun mapPayoutError(error: PayOutError): String {
    return when (error.errorCode) {
        "PO02" -> "The payout amount must be greater than zero."
        "PO03" -> "Please specify a valid currency."
        "PO04" -> "Please verify your PayPal account information."
        "PO07" -> "The transaction date is invalid. Use ISO 8601 format."
        "PO01" -> "The payout could not be completed. Please try again."
        else -> error.errorReason ?: "Something went wrong. Please try again."
    }
}

// In PayoutSubmissionComponentConfig
onError = { error ->
    showErrorDialog(mapPayoutError(error))
}