{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-android/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["code-walkthrough","admonition","step"]},"type":"markdown"},"seo":{"title":"Error Reference | Finix Android Reference","description":"Reference for FinixErrorCode — the structured failure value returned by the Finix Android PaymentSheet onFailure callback.","siteUrl":"https://docs.finix.com/","llmstxt":{"hide":false,"sections":[{"title":"Getting Started","includeFiles":["guides/getting-started/**/*.md"],"excludeFiles":[]},{"title":"Online Payments","includeFiles":["guides/online-payments/**/*.md"],"excludeFiles":["guides/online-payments/payment-features/fsa-hsa-non-healthcare-mcc.md"]},{"title":"In-Person Payments","includeFiles":["guides/in-person-payments/**/*.md"],"excludeFiles":[]},{"title":"Subscriptions","includeFiles":["guides/subscriptions/**/*.md"],"excludeFiles":[]},{"title":"After the Payment","includeFiles":["guides/after-the-payment/**/*.md"],"excludeFiles":[]},{"title":"Managing Operations","includeFiles":["guides/managing-operations/**/*.md"],"excludeFiles":[]},{"title":"Platform Payments","includeFiles":["guides/platform-payments/**/*.md"],"excludeFiles":[]},{"title":"Payouts","includeFiles":["guides/payouts/**/*.md"],"excludeFiles":[]},{"title":"Low-Code / No-Code","includeFiles":["low-code-no-code/**/*.md"],"excludeFiles":[]},{"title":"Developers","includeFiles":["additional-resources/developers/**/*.md"],"excludeFiles":[]},{"title":"Plugins","includeFiles":["additional-resources/plugins/**/*.md"],"excludeFiles":[]},{"title":"Industry Considerations","includeFiles":["guides/industry-considerations/**/*.md"],"excludeFiles":[]},{"title":"Regional Considerations","includeFiles":["guides/regional-considerations/**/*.md"],"excludeFiles":[]},{"title":"Release Notes","includeFiles":["release-notes/**/*.md"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeWalkthrough","attributes":{"__idx":1,"filters":{},"filesets":[{"files":[{"path":"android/online/_filesets/errors.kt","content":[{"start":0,"condition":{"steps":["error-code-shape"]},"children":["sealed interface FinixErrorCode {","    val message: String","","    data object NetworkError : FinixErrorCode {","        override val message = \"Network error. Please check your connection.\"","    }","","    data object Timeout : FinixErrorCode {","        override val message = \"Request timed out. Please try again.\"","    }","","    data object PaymentFailed : FinixErrorCode {","        override val message = \"Payment failed. Please try again.\"","    }","","    data class MissingConfiguration(val field: String) : FinixErrorCode {","        override val message = \"3DS is enabled but required field '$field' is missing.\"","    }","","    data class ThreeDSFailed(val failureCode: ThreeDSFailureCode?) : FinixErrorCode {","        override val message =","            failureCode?.failureMessage ?: \"3DS authentication failed. Please try again.\"","    }","","    data class Unknown(val detail: String = \"\") : FinixErrorCode {","        override val message = detail.ifEmpty { \"An unexpected error occurred.\" }","    }","}"]},"",{"start":31,"condition":{"steps":["threeds-failure-codes"]},"children":["enum class ThreeDSFailureCode(val failureMessage: String) {","    ACCESS_CONTROL_SERVER_UNAVAILABLE(","        \"The card issuer's authentication server was unavailable. Retry later.\"","    ),","    AUTHENTICATION_FAILED(","        \"The cardholder failed to provide the correct authentication details. \" +","            \"This transaction should be considered potentially fraudulent.\"","    ),","    AUTHENTICATION_TIMED_OUT(","        \"The authentication timed out, likely because the cardholder abandoned the transaction.\"","    ),","    CARD_NOT_ENROLLED(","        \"The card is not enrolled in 3DS and cannot be authenticated.\"","    ),","    CHALLENGE_REQUIRED(","        \"A challenge was required but the integration is configured to fail on challenge.\"","    ),","    DIRECTORY_SERVER_UNAVAILABLE(","        \"The card network's directory server was unavailable. Retry later.\"","    ),","    INVALID_ACQUIRER(","        \"The acquirer details provided are invalid.\"","    ),","    INVALID_CARD(","        \"The card details are invalid.\"","    ),","    PROTOCOL_ERROR(","        \"A protocol error occurred during the authentication process.\"","    ),","    REQUIRED_DATA_ELEMENT_MISSING(","        \"A required data element is missing from the authentication request.\"","    ),","    SUSPECTED_FRAUD(","        \"The transaction was flagged as suspected fraud by the issuer.\"","    ),","    TRANSACTION_CANCELLED_BY_CARDHOLDER(","        \"The cardholder explicitly cancelled the authentication challenge.\"","    ),","    TRANSACTION_NOT_PERMITTED(","        \"The transaction type is not permitted for this card.\"","    ),","    TRANSIENT_SYSTEM_FAILURE(","        \"A transient system failure occurred. Retry later.\"","    ),","    UNSUPPORTED_3D_SECURE_VERSION(","        \"The 3D Secure version required by the issuer is not supported.\"","    ),","}"]},"",{"start":82,"condition":{"steps":["handling"]},"children":["onFailure = { code ->","    when (code) {","        FinixErrorCode.NetworkError,","        FinixErrorCode.Timeout -> showError(code.message)","        FinixErrorCode.PaymentFailed -> showError(code.message)","        is FinixErrorCode.MissingConfiguration ->","            // Bug in the integration — missing field named by code.field","            logConfigurationError(code.field)","        is FinixErrorCode.ThreeDSFailed ->","            // No liability shift — do not charge","            showError(code.message)","        is FinixErrorCode.Unknown -> showError(code.message)","    }","}"]},""],"metadata":{"steps":["error-code-shape","threeds-failure-codes","handling"]},"basename":"errors.kt","language":"kotlin"}],"downloadAssociatedFiles":[]}],"steps":[{"id":"error-code-shape","heading":"FinixErrorCode shape"},{"id":"threeds-failure-codes","heading":"ThreeDSFailureCode cases"},{"id":"handling","heading":"Handling onFailure"}],"inputs":{},"toggles":{}},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"error-reference","__idx":0},"children":["Error Reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tokenization and 3D Secure failures are reported through ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/android/online/payment-sheet"},"children":["CompletePaymentSheet"]},"'s ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onFailure"]}," callback. Each failure carries a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FinixErrorCode"]}," describing the exact failure mode."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Deprecated signature"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The deprecated signature had no failure callback — errors were surfaced via a toast inside the sheet. If you're still using the deprecated signature, tokenization errors won't reach your code. Migrate to the new ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/android/online/payment-sheet"},"children":["CompletePaymentSheet"]}," signature."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"finixerrorcode","__idx":1},"children":["FinixErrorCode"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A sealed interface — pattern-match on the specific type in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["when"]}," to branch per failure mode. Every variant carries a human-readable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," suitable for surfacing to the buyer."]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"error-code-shape","heading":"FinixErrorCode shape"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"sealed interface FinixErrorCode {\n    val message: String\n\n    data object NetworkError : FinixErrorCode {\n        override val message = \"Network error. Please check your connection.\"\n    }\n\n    data object Timeout : FinixErrorCode {\n        override val message = \"Request timed out. Please try again.\"\n    }\n\n    data object PaymentFailed : FinixErrorCode {\n        override val message = \"Payment failed. Please try again.\"\n    }\n\n    data class MissingConfiguration(val field: String) : FinixErrorCode {\n        override val message = \"3DS is enabled but required field '$field' is missing.\"\n    }\n\n    data class ThreeDSFailed(val failureCode: ThreeDSFailureCode?) : FinixErrorCode {\n        override val message =\n            failureCode?.failureMessage ?: \"3DS authentication failed. Please try again.\"\n    }\n\n    data class Unknown(val detail: String = \"\") : FinixErrorCode {\n        override val message = detail.ifEmpty { \"An unexpected error occurred.\" }\n    }\n}\n","lang":"kotlin"},"children":[]},{"$$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":"Variant"},"children":["Variant"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NetworkError"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The device could not reach Finix (no connectivity, DNS failure, TLS error)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Timeout"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Finix API call did not return within the SDK's timeout window."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PaymentFailed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tokenization reached Finix but did not succeed. Typically an invalid or declined card."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MissingConfiguration(field)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3DS was enabled but a required field is missing from ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/android/online/configuration"},"children":["PaymentSheetConfiguration"]}," — the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["field"]}," property names which one (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"merchantId\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"apiUsername\""]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ThreeDSFailed(failureCode)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3D Secure authentication failed. The nested ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#threedsfailurecode"},"children":["ThreeDSFailureCode"]}," describes the specific reason. No liability shift — do not charge."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Unknown(detail)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An unexpected error. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]}," carries any available context from the SDK."]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"threedsfailurecode","__idx":2},"children":["ThreeDSFailureCode"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Nested inside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FinixErrorCode.ThreeDSFailed"]}," and populated on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ThreeDSResponse.failureCode"]},". Each case carries a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failureMessage"]}," string explaining the failure."]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"threeds-failure-codes","heading":"ThreeDSFailureCode cases"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"enum class ThreeDSFailureCode(val failureMessage: String) {\n    ACCESS_CONTROL_SERVER_UNAVAILABLE,\n    AUTHENTICATION_FAILED,\n    AUTHENTICATION_TIMED_OUT,\n    CARD_NOT_ENROLLED,\n    CHALLENGE_REQUIRED,\n    DIRECTORY_SERVER_UNAVAILABLE,\n    INVALID_ACQUIRER,\n    INVALID_CARD,\n    PROTOCOL_ERROR,\n    REQUIRED_DATA_ELEMENT_MISSING,\n    SUSPECTED_FRAUD,\n    TRANSACTION_CANCELLED_BY_CARDHOLDER,\n    TRANSACTION_NOT_PERMITTED,\n    TRANSIENT_SYSTEM_FAILURE,\n    UNSUPPORTED_3D_SECURE_VERSION,\n}\n","lang":"kotlin"},"children":[]},{"$$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":"Case"},"children":["Case"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCESS_CONTROL_SERVER_UNAVAILABLE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card issuer's authentication server was unavailable. Retry later."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTHENTICATION_FAILED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The cardholder failed to provide the correct authentication details. Treat as potentially fraudulent."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTHENTICATION_TIMED_OUT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authentication timed out, likely because the cardholder abandoned the transaction."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CARD_NOT_ENROLLED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card is not enrolled in 3DS and cannot be authenticated."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHALLENGE_REQUIRED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A challenge was required but the integration is configured to fail on challenge."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DIRECTORY_SERVER_UNAVAILABLE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card network's directory server was unavailable. Retry later."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_ACQUIRER"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The acquirer details provided are invalid."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_CARD"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card details are invalid."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PROTOCOL_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A protocol error occurred during authentication."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REQUIRED_DATA_ELEMENT_MISSING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A required data element is missing from the authentication request."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SUSPECTED_FRAUD"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The transaction was flagged as suspected fraud by the issuer."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSACTION_CANCELLED_BY_CARDHOLDER"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The cardholder explicitly cancelled the authentication challenge."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSACTION_NOT_PERMITTED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The transaction type is not permitted for this card."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSIENT_SYSTEM_FAILURE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A transient system failure occurred. Retry later."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNSUPPORTED_3D_SECURE_VERSION"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The 3D Secure version required by the issuer is not supported."]}]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeStep","attributes":{"id":"handling","heading":"Handling onFailure"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pattern-match on the error code to branch per failure mode. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," is safe to surface directly to the buyer."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","header":{"controls":{"copy":{}}},"source":"onFailure = { code ->\n    when (code) {\n        FinixErrorCode.NetworkError,\n        FinixErrorCode.Timeout -> showError(code.message)\n        FinixErrorCode.PaymentFailed -> showError(code.message)\n        is FinixErrorCode.MissingConfiguration ->\n            // Bug in the integration — missing field named by code.field\n            logConfigurationError(code.field)\n        is FinixErrorCode.ThreeDSFailed ->\n            // No liability shift — do not charge\n            showError(code.message)\n        is FinixErrorCode.Unknown -> showError(code.message)\n    }\n}\n","lang":"kotlin"},"children":[]}]}]}]},"headings":[{"value":"Error Reference","id":"error-reference","depth":1},{"value":"FinixErrorCode","id":"finixerrorcode","depth":2},{"value":"ThreeDSFailureCode","id":"threedsfailurecode","depth":2}],"frontmatter":{"seo":{"title":"Error Reference | Finix Android Reference","description":"Reference for FinixErrorCode — the structured failure value returned by the Finix Android PaymentSheet onFailure callback."},"markdown":{"toc":{"hide":true}},"footer":{"hide":true}},"lastModified":"2026-10-15T20:17:30.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/android/online/errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}