# Error codes

See the definitions of the error codes you may receive when integrating Flow for mobile.

| Error | Description |
| --- | --- |
| `BASE64_ENCODING_FAILED` | The encoding of the `sessionData` passed to the `handleSubmit` callback failed. |
| `CALLBACK_NOT_PROVIDED` | You must provide the `onTokenized()` [callback](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/flow-for-mobile-library-reference/android/componentcallback.md#onTokenized(TokenDetails)) before you call the `tokenize()` [method](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/flow-for-mobile-library-reference/android/paymentmethodcomponent.md#tokenize()). |
| `CARD_AUTHENTICATION_FAILED` | The 3DS authentication challenge did not complete. This happens when the customer cancels the challenge, dismisses it before completion, or the SDK cannot launch the challenge because of a missing `Activity` context.<br><br>The `message` property indicates which case occurred:<br><br>- `Payment authentication cancelled by user` – The customer explicitly canceled the challenge.<br>- `Payment authentication challenge dismissed` – The customer closed the challenge before completion.<br>- `3DS challenge requires an Activity context.` – This is an integration error. Initialize the SDK with an `Activity`-backed context. |
| `COMPONENT_INVALID` | The selected component's inputs are invalid.<br><br>For the `Flow` component, this is also called if there are no embedded components selected. |
| `COMPONENT_IS_AVAILABLE_NOT_CHECKED` | The `isAvailable()` method was not called before rendering the `PaymentMethodComponent`. The component may not be supported by the customer's device.<br><br>After you create the `PaymentMethodComponent`, call the `isAvailable()` method to verify that the device supports the payment method. This does not apply to the `CheckoutComponent`. |
| `COMPONENT_NOT_SUPPORTED` | The name specified when creating the `PaymentMethodComponent` using the `create()` method is not supported.<br><br>If you provide `enabled_payment_methods` or `disabled_payment_methods` options when you [create the payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/get-started-with-flow-for-mobile.md#Create_a_new_Payment_Session_), ensure you also include the payment method that you want to offer.<br><br>You must also ensure that the `currency` and `billing.address.country` values you provide to the payment session match the payment method's requirements. |
| `CONFIGURATION_INVALID` | After you create a payment session in your server-side integration, ensure you return the public key and the entire `PaymentSession` response object to the client-side and provide it to Flow for mobile. |
| `DEPENDENCY_NOT_PROVIDED` | No tokenize handler is configured for the component. |
| `INVALID_SETUP` | The SDK was initialized or invoked with an invalid setup. For example:<br><br>- Missing or malformed `publicKey`<br>- Missing or partial payment session<br>- Calling methods in the wrong order<br>- Using unsupported configuration combinations<br><br>Review your initialization of Flow for Mobile and the payment session payload, then re-create the session and retry. |
| `MERCHANT_HANDLE_SUBMIT_CALLBACK_FAILED` | The payment session submission sent with the `handleSubmit` callback failed. |
| `METHOD_NOT_SUPPORTED` | The `tokenize()` method is not supported for the selected component.<br><br>For the `Flow` component, this is also called if a card component is not embedded. |
| `PAYMENT_CANCELLED` | The payment attempt was cancelled before completion. For example, the customer closed the Google Pay screen. |
| `PAYMENT_METHOD_ATTEMPT_FAILED` | The payment attempt for the payment method specified in `details.type` encountered an unexpected failure.<br><br>Unexpected failures may occur when Flow integrates with a payment method's client-side library, or makes network requests to the payment method's endpoints.<br><br>If you persistently encounter the error for a specific payment method, this could be caused by your account configuration. For example, incomplete onboarding to a payment method. Contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_integration&issue=case_integration_issue_other). |
| `PAYMENT_REQUEST_DECLINED` | The payment request was declined. This occurs in the following situations:<br><br>- The payment session was declined – The payment ID is provided in the `details.paymentId` property. You can fetch the details of the payment by calling the [Get payment details](https://www.checkout.com/docs/payments/manage-payments/get-payment-details.md) endpoint, or searching for the payment record in the Dashboard. The `details.requestErrorCodes` property contains one of the following error codes:<br><br>- `not_enough_funds` – The customer does not have enough funds for the transaction.<br>- `invalid_payment_session_data` – You provided invalid details when creating the payment session. See the [API reference](https://api-reference.checkout.com/tag/Flow/#operation/CreatePaymentSession) for additional field details.<br>- `invalid_customer_data` – The customer provided invalid details.<br>- `merchant_misconfiguration` – Your account has invalid configurations.<br>- `try_again` – The payment request was declined due to technical issues. Contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).<br><br>Flow automatically displays error messages to the customer, with suggested next actions to improve retry success.<br><br>- The customer completes the 3DS challenge, but the payment was declined – The SDK reports this with `PAYMENT_REQUEST_DECLINED` set to `code` and provides the reason in `error.message`.<br><br>- If a decline reason exists, `error.message` returns `The payment request was declined. Decline reason: <reason>`.<br>- If no decline reason exists, `error.message` returns `The payment request was declined`.<br><br>Display a generic, localized message to the customer. The `<reason>` value (for example, `insufficient_funds`, or `do_not_honor`) is the decline reason response from the issuer or acquirer. Use it for internal purposes only. |
| `PAYMENT_REQUEST_FAILED` | The payment request failed due to unexpected error or network issue.<br><br>Any additional error codes from the network requests are provided in the `details.requestErrorCodes` property. See the possible [error codes](https://www.checkout.com/docs/developer-resources/codes/error-codes.md#Payments_endpoint) for the Request a payment endpoint for more details. Customers can typically complete their payment after a retry.<br><br>If you persistently encounter the error for a specific payment method, this could be caused by your account configuration. Contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). |
| `PAYMENT_SESSION_FAILED` | The payment session request failed due to unexpected error or network issue.<br><br>If you persistently encounter the error for a specific payment method, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). |
| `SERVER_COMMUNICATION_ERROR` | A required backend response could not be retrieved due to a network or server issue.<br><br>Check connectivity and server availability, inspect any attached request error details, and retry. If the issue persists, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). |
| `SUBMISSION_PARSE_ERROR` | The result of the payment submission could not be parsed. |
| `TOKENIZE_REQUEST_FAILED` | The CVV component's tokenization request failed. The error arrives as one of two subtypes, which tells you whether retrying is worthwhile:<br><br>- `CheckoutError.Request` – The request reached the server and was rejected, or the network call itself failed. Its `details` carry the HTTP `status` plus the server's `requestId` and `requestErrorCodes`. Quote these values to support.<br>- `CheckoutError.Internal` – A response arrived but could not be interpreted, for example a success response with a missing or malformed body. Retrying is unlikely to help. |
| `UPDATE_PARAMETER_INVALID` | The `updateDetails` passed to the `CheckoutComponents.update()` method contains invalid values. |
| `VALIDATION_FAILED` | One or more input values failed client-side validation for the selected component. Ensure all required fields are present and correctly formatted, update the inputs, and retry the operation. |