CryptoOnramp SDK: API Error Refactor

CHANGELOG.md

@@ -6,6 +6,11 @@ NEXT_VERSION_BUMP: PATCH
 ### Payments
 * [CHANGED][13144](https://github.com/stripe/stripe-android/pull/13144) On payment or setup confirmation failure, we now include error code, decline code, and error type in the exception thrown.
 
+### CryptoOnramp
+* [ADDED][13156](https://github.com/stripe/stripe-android/pull/13156) Added `CryptoOnrampException`, `AppAttestationException`, and `UncategorizedApiErrorException` to expose richer developer-facing diagnostics and preserved backend API error context for Crypto Onramp failures.
+* [CHANGED][13156](https://github.com/stripe/stripe-android/pull/13156) Improved Crypto Onramp API error handling with localized fallback user messaging and more consistent error mapping across attestation, payment collection, and checkout flows.
+
+
 ## 23.9.1 - 2026-05-26
 
 ### Payments

crypto-onramp/api/crypto-onramp.api

@@ -34,6 +34,56 @@ public final class com/stripe/android/crypto/onramp/OnrampCoordinator$Presenter
 	public static synthetic fun verifyKycInfo$default (Lcom/stripe/android/crypto/onramp/OnrampCoordinator$Presenter;Lcom/stripe/android/paymentsheet/PaymentSheet$Address;ILjava/lang/Object;)V
 }
 
+public final class com/stripe/android/crypto/onramp/exception/APIErrorContext {
+	public static final field $stable I
+	public fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcom/stripe/android/core/exception/StripeException;)V
+	public final fun component1 ()Ljava/lang/String;
+	public final fun component10 ()Ljava/lang/String;
+	public final fun component11 ()Lcom/stripe/android/core/exception/StripeException;
+	public final fun component2 ()Ljava/lang/String;
+	public final fun component3 ()Ljava/lang/String;
+	public final fun component4 ()Ljava/lang/String;
+	public final fun component5 ()Ljava/lang/String;
+	public final fun component6 ()Ljava/lang/String;
+	public final fun component7 ()Ljava/lang/String;
+	public final fun component8 ()Ljava/lang/String;
+	public final fun component9 ()Ljava/lang/String;
+	public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcom/stripe/android/core/exception/StripeException;)Lcom/stripe/android/crypto/onramp/exception/APIErrorContext;
+	public static synthetic fun copy$default (Lcom/stripe/android/crypto/onramp/exception/APIErrorContext;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcom/stripe/android/core/exception/StripeException;ILjava/lang/Object;)Lcom/stripe/android/crypto/onramp/exception/APIErrorContext;
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getApiErrorCode ()Ljava/lang/String;
+	public final fun getApiErrorMessage ()Ljava/lang/String;
+	public final fun getApiErrorType ()Ljava/lang/String;
+	public final fun getApiUserMessage ()Ljava/lang/String;
+	public final fun getAppPackageName ()Ljava/lang/String;
+	public final fun getDocUrl ()Ljava/lang/String;
+	public final fun getMode ()Ljava/lang/String;
+	public final fun getOperation ()Ljava/lang/String;
+	public final fun getReason ()Ljava/lang/String;
+	public final fun getRequestId ()Ljava/lang/String;
+	public final fun getSdkVersion ()Ljava/lang/String;
+	public final fun getUnderlyingError ()Lcom/stripe/android/core/exception/StripeException;
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class com/stripe/android/crypto/onramp/exception/AppAttestationException : com/stripe/android/crypto/onramp/exception/CryptoOnrampApiException {
+	public static final field $stable I
+	public fun getUserMessage ()Ljava/lang/String;
+}
+
+public abstract class com/stripe/android/crypto/onramp/exception/CryptoOnrampApiException : com/stripe/android/crypto/onramp/exception/CryptoOnrampException {
+	public static final field $stable I
+	public final fun getContext ()Lcom/stripe/android/crypto/onramp/exception/APIErrorContext;
+}
+
+public abstract class com/stripe/android/crypto/onramp/exception/CryptoOnrampException : com/stripe/android/core/exception/StripeException {
+	public static final field $stable I
+	public final fun getDeveloperMessage ()Ljava/lang/String;
+	public final fun getStripeException ()Lcom/stripe/android/core/exception/StripeException;
+	public abstract fun getUserMessage ()Ljava/lang/String;
+}
+
 public final class com/stripe/android/crypto/onramp/exception/MissingConsumerSecretException : java/lang/IllegalStateException {
 	public static final field $stable I
 }
@@ -55,6 +105,11 @@ public final class com/stripe/android/crypto/onramp/exception/PaymentFailedExcep
 	public static final field $stable I
 }
 
+public final class com/stripe/android/crypto/onramp/exception/UncategorizedApiErrorException : com/stripe/android/crypto/onramp/exception/CryptoOnrampApiException {
+	public static final field $stable I
+	public fun getUserMessage ()Ljava/lang/String;
+}
+
 public final class com/stripe/android/crypto/onramp/model/CryptoNetwork : java/lang/Enum {
 	public static final field Aptos Lcom/stripe/android/crypto/onramp/model/CryptoNetwork;
 	public static final field Arbitrum Lcom/stripe/android/crypto/onramp/model/CryptoNetwork;

crypto-onramp/res/values/strings.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+  <!-- Fallback app-user message for Crypto Onramp app attestation failures. -->
+  <string name="stripe_onramp_app_attestation_default_user_message">This app couldn\'t be verified due to an attestation error. Please try again later or contact the developer if the issue persists.</string>
+  <!-- Fallback app-user message for uncategorized Crypto Onramp API failures. -->
+  <string name="stripe_onramp_default_api_error_user_message">Something went wrong. Please try again later.</string>
+</resources>