{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading","admonition"]},"type":"markdown"},"seo":{"title":"Error handling","description":"Transform your commerce with PXP's unified platform—seamless payments, real-time insights, and global growth in one powerful integration.","lang":"en-UK","siteUrl":"https://developer.pxp.io"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"error-handling","__idx":0},"children":["Error handling"]},{"$$mdtype":"Tag","name":"SubHeading","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Handle payout component errors in the Android SDK."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payout components on Android report validation and execution failures with payout-specific codes in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PO0x"]}," range, plus related OAuth codes in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OA0x"]}," range when you use an OAuth submission flow. Submission failures are delivered to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," as a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayOutError"]},", which exposes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorReason"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/components/android/paypal/data-validation"},"children":["Data validation"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-errors-are-raised","__idx":2},"children":["When errors are raised"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following table summarises where payout errors appear."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Stage"},"children":["Stage"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"How you receive the error"},"children":["How you receive the error"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["SDK initialisation and component validation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Thrown as validation errors. For example an invalid amount, currency, email, or payer ID."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payout submission"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delivered through the submission component ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," callback as a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayOutError"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["proceedPayoutWithSdk"]}," set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},", the SDK calls ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["proceedPayoutWithSdk"]}," set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPrePayoutSubmit"]}," is missing or returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isApproved = false"]},", the SDK cancels the payout and does not call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},". Handle that case in your approval UI."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-codes","__idx":3},"children":["Error codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following tables list payout-related codes from the Android SDK."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payout-validation-and-execution","__idx":4},"children":["Payout validation and execution"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error code"},"children":["Error code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PO01"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["General payout error."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PO02"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction amount should be greater than 0."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PO03"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid currency code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PO04"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid 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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Paypal"]}," is supported as the recipient wallet."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PO07"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid or missing merchant transaction date. Use the ISO 8601 format (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2025-10-28T10:00:00Z"]},")."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Amount and currency display components may also surface string codes such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AMOUNT_MUST_BE_POSITIVE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_NUMERIC"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_CURRENCY"]}," during local validation. Treat those as validation failures and correct ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionData"]}," before submission."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"oauth-related-codes","__idx":5},"children":["OAuth-related codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you use the PayPal OAuth submission flow, the SDK may also report the following codes."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error code"},"children":["Error code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OA01"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["General OAuth error."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OA02"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid OAuth state."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OA03"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid OAuth authorisation code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OA04"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OAuth timeout."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example","__idx":6},"children":["Example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example maps common payout codes from a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayOutError"]}," to customer-facing messages:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"fun mapPayoutError(error: PayOutError): String {\n    return when (error.errorCode) {\n        \"PO02\" -> \"The payout amount must be greater than zero.\"\n        \"PO03\" -> \"Please specify a valid currency.\"\n        \"PO04\" -> \"Please verify your PayPal account information.\"\n        \"PO07\" -> \"The transaction date is invalid. Use ISO 8601 format.\"\n        \"PO01\" -> \"The payout could not be completed. Please try again.\"\n        else -> error.errorReason ?: \"Something went wrong. Please try again.\"\n    }\n}\n\n// In PayoutSubmissionComponentConfig\nonError = { error ->\n    showErrorDialog(mapPayoutError(error))\n}\n","lang":"kotlin"},"children":[]}]},"headings":[{"value":"Error handling","id":"error-handling","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"When errors are raised","id":"when-errors-are-raised","depth":2},{"value":"Error codes","id":"error-codes","depth":2},{"value":"Payout validation and execution","id":"payout-validation-and-execution","depth":3},{"value":"OAuth-related codes","id":"oauth-related-codes","depth":3},{"value":"Example","id":"example","depth":2}],"frontmatter":{"seo":{"title":"Error handling"}},"lastModified":"2026-11-11T13:23:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/payout/components/android/paypal/error-handling","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}