Expose private suspend funs in clients (#1628)

* feat(ThreeDS): Add suspend equivalent for createPaymentAuthRequest

* feat: Expose suspend function equivalents for public callback based functions.

* Update KDoc to improve clarity and accuracy.

# Conflicts:
#	CHANGELOG.md

* chore: Clean up warnings for unused parameters.

* fix: Respond to PR comments

* Whitespace clean up
* Grammar fixes

* fix: Respond to PR comments

* Whitespace clean up
* Comment verbiage updates

Author: mzlangreder

AmericanExpress/src/main/java/com/braintreepayments/api/americanexpress/AmericanExpressClient.kt

@@ -51,7 +51,14 @@ class AmericanExpressClient internal constructor(
         }
     }
 
-    private suspend fun getRewardsBalance(
+    /**
+     * Gets the rewards balance associated with a Braintree nonce. Only for American Express cards.
+     *
+     * @param nonce   A nonce representing a card that will be used to look up the rewards balance
+     * @param currencyIsoCode The currencyIsoCode to use. Example: 'USD'
+     * @return result [AmericanExpressResult]
+     */
+    suspend fun getRewardsBalance(
         nonce: String,
         currencyIsoCode: String
     ): AmericanExpressResult {

CHANGELOG.md

@@ -1,7 +1,38 @@
 # Braintree Android SDK Release Notes
 
-## 5.29.0 (2026-06-30)
+## unreleased
 
+* AmericanExpress
+    * Expose `getRewardsBalance` as a public suspend function
+* Card
+    * Expose `tokenize` as a public suspend function
+* GooglePay
+    * Expose `isReadyToPay` as a public suspend function
+    * Expose `getTokenizationParameters` as a public suspend function
+    * Expose `createPaymentAuthRequest` as a public suspend function
+* LocalPayment
+    * Expose `createPaymentAuthRequest` as a public suspend function
+    * Expose `tokenize` as a public suspend function
+* PayPal
+    * Expose `createPaymentAuthRequest` as a public suspend function
+    * Expose `tokenize` as a public suspend function
+* SEPADirectDebit
+    * Expose `createPaymentAuthRequest` as a public suspend function
+    * Expose `tokenize` as a public suspend function
+* ShopperInsights
+    * Expose `createCustomerSession` as a public suspend function
+    * Expose `updateCustomerSession` as a public suspend function
+    * Expose `generateCustomerRecommendations` as a public suspend function
+* ThreeDSecure
+    * Expose `createPaymentAuthRequest` as a public suspend function
+    * Expose `prepareLookup` as a public suspend function
+    * Expose `initializeChallengeWithLookupResponse` as a public suspend function
+    * Expose `tokenize` as a public suspend function
+* Venmo
+    * Expose `createPaymentAuthRequest` as a public suspend function
+    * Expose `tokenize` as a public suspend function
+  
+## 5.29.0 (2026-06-30)
 * GooglePay
     * Remove requirement for `GooglePayActivity` to be declared in the Android manifest (fixes #1572)
         * Note: If upgrading from v4, any manual `GooglePayActivity` declaration in your app's manifest should be removed

Card/src/main/java/com/braintreepayments/api/card/CardClient.kt

@@ -42,19 +42,15 @@ class CardClient internal constructor(
     )
 
     /**
-     * Create a [CardNonce].
+     * Creates a [CardNonce].
      *
      * The tokenization result is returned via a [CardTokenizeCallback] callback.
      *
-     * On success, the [CardTokenizeCallback.onCardResult] method will be
-     * invoked with a [CardResult.Success] including a nonce.
+     * On success the [CardTokenizeCallback.onCardResult] method will be
+     * invoked with a [CardResult.Success] containing a nonce.
      *
-     * If creation fails validation, the [CardTokenizeCallback.onCardResult]
-     * method will be invoked with a [CardResult.Failure] including an exception.
-     *
-     * If an error not due to validation (server error, network issue, etc.) occurs, the
-     * [CardTokenizeCallback.onCardResult] method will be invoked with a
-     * [CardResult.Failure] with an [Exception] describing the error.
+     * On failure the [CardTokenizeCallback.onCardResult] method will be
+     * invoked with a [CardResult.Failure] containing an exception.
      *
      * @param card     [Card]
      * @param callback [CardTokenizeCallback]
@@ -66,7 +62,17 @@ class CardClient internal constructor(
         }
     }
 
-    private suspend fun tokenize(card: Card): CardResult {
+    /**
+     * Creates a [CardNonce].
+     *
+     * On success [CardResult.Success] containing a [CardNonce] is returned.
+     *
+     * On failure [CardResult.Failure] containing an exception is returned.
+     *
+     * @param card [Card]
+     * @return [CardResult]
+     */
+    suspend fun tokenize(card: Card): CardResult {
         analyticsParamRepository.reset()
         braintreeClient.sendAnalyticsEvent(CardAnalytics.CARD_TOKENIZE_STARTED)
         return try {

GooglePay/src/main/java/com/braintreepayments/api/googlepay/GooglePayClient.kt

@@ -31,7 +31,6 @@ import kotlinx.coroutines.launch
 import org.json.JSONArray
 import org.json.JSONException
 import org.json.JSONObject
-import kotlin.toString
 
 /**
  * Used to create and tokenize Google Pay payment methods. For more information see the [documentation](https://developer.paypal.com/braintree/docs/guides/google-pay/overview)
@@ -76,8 +75,10 @@ class GooglePayClient internal constructor(
 
     /**
      * Before starting the Google Pay flow, use this method to check whether the Google Pay API is
-     * supported and set up on the device. When the callback is called with `true`, show the
-     * Google Pay button. When it is called with `false`, display other checkout options.
+     * supported and set up on the device.
+     *
+     * When [callback] is called with [GooglePayReadinessResult.ReadyToPay], show the Google Pay Button.
+     * When [callback] is called with [GooglePayReadinessResult.NotReadyToPay], display other checkout options.
      *
      * @param context  Android Context
      * @param request  [ReadyForGooglePayRequest]
@@ -95,9 +96,20 @@ class GooglePayClient internal constructor(
         }
     }
 
-    private suspend fun isReadyToPay(context: Context, request: ReadyForGooglePayRequest?): GooglePayReadinessResult {
+    /**
+     * Before starting the Google Pay flow, use this method to check whether the Google Pay API is
+     * supported and set up on the device.
+     *
+     * When the return value is [GooglePayReadinessResult.ReadyToPay], show the Google Pay Button.
+     * When the Return value is [GooglePayReadinessResult.NotReadyToPay], display other checkout options.
+     *
+     * @param context  Android Context
+     * @param request  [ReadyForGooglePayRequest]
+     * @return [GooglePayReadinessResult]
+     */
+    suspend fun isReadyToPay(context: Context, request: ReadyForGooglePayRequest?): GooglePayReadinessResult {
         return try {
-            Class.forName(PaymentsClient::class.java.name)
+            verifyGoogleWalletOnClasspath()
             val configuration = braintreeClient.getConfiguration()
             if (!configuration.isGooglePayEnabled) {
                 NotReadyToPay(null)
@@ -125,7 +137,7 @@ class GooglePayClient internal constructor(
                             request.isExistingPaymentMethodRequired
                         )
                     }
-                } catch (ignored: JSONException) {
+                } catch (_: JSONException) {
                 }
                 val readyToPayRequest = IsReadyToPayRequest.fromJson(json.toString())
                 internalGooglePayClient.isReadyToPay(
@@ -140,6 +152,15 @@ class GooglePayClient internal constructor(
         }
     }
 
+    @Throws(
+        LinkageError::class,
+        ExceptionInInitializerError::class,
+        ClassNotFoundException::class
+    )
+    private fun verifyGoogleWalletOnClasspath() {
+        Class.forName(PaymentsClient::class.java.name)
+    }
+
     /**
      * Get Braintree specific tokenization parameters for a Google Pay. Useful for when full control
      * over the [PaymentDataRequest] is required.
@@ -150,7 +171,7 @@ class GooglePayClient internal constructor(
      * [PaymentDataRequest.Builder.setPaymentMethodTokenizationParameters]
      * and [allowedCardNetworks] should be supplied to the
      * [CardRequirements] via
-     * [CardRequirements.Builder.addAllowedCardNetworks]}.
+     * [CardRequirements.Builder.addAllowedCardNetworks].
      *
      * @param callback [GooglePayGetTokenizationParametersCallback]
      */
@@ -163,7 +184,21 @@ class GooglePayClient internal constructor(
         }
     }
 
-    private suspend fun getTokenizationParameters(): GooglePayTokenizationParameters {
+    /**
+     * Get Braintree specific tokenization parameters for a Google Pay. Useful for when full control
+     * over the [PaymentDataRequest] is required.
+     *
+     *
+     * [PaymentMethodTokenizationParameters] should be supplied to the
+     * [PaymentDataRequest] via
+     * [PaymentDataRequest.Builder.setPaymentMethodTokenizationParameters]
+     * and [allowedCardNetworks] should be supplied to the
+     * [CardRequirements] via
+     * [CardRequirements.Builder.addAllowedCardNetworks].
+     *
+     * @return [GooglePayTokenizationParameters]
+     */
+    suspend fun getTokenizationParameters(): GooglePayTokenizationParameters {
         return try {
             val configuration = braintreeClient.getConfiguration()
             GooglePayTokenizationParameters.Success(
@@ -181,7 +216,7 @@ class GooglePayClient internal constructor(
      * used to present Google Pay payment sheet in
      * [GooglePayLauncher.launch]
      *
-     * @param request  The [GooglePayRequest] containing options for the transaction.
+     * @param request The [GooglePayRequest] containing options for the transaction.
      * @param callback [GooglePayPaymentAuthRequestCallback]
      */
     fun createPaymentAuthRequest(
@@ -203,7 +238,15 @@ class GooglePayClient internal constructor(
         }
     }
 
-    private suspend fun createPaymentAuthRequest(request: GooglePayRequest): GooglePayPaymentAuthRequest {
+    /**
+     * Start the Google Pay payment flow. This will return [GooglePayPaymentAuthRequestParams] that are
+     * used to present Google Pay payment sheet in
+     * [GooglePayLauncher.launch]
+     *
+     * @param request The [GooglePayRequest] containing options for the transaction.
+     * @return [GooglePayPaymentAuthRequest]
+     */
+    suspend fun createPaymentAuthRequest(request: GooglePayRequest): GooglePayPaymentAuthRequest {
         analyticsParamRepository.reset()
         braintreeClient.sendAnalyticsEvent(GooglePayAnalytics.PAYMENT_REQUEST_STARTED)
 
@@ -238,13 +281,16 @@ class GooglePayClient internal constructor(
     /**
      * Call this method when you've received a successful [PaymentData] response from a
      * direct Google Play Services integration to get a [GooglePayCardNonce] or
-     * [PayPalAccountNonce].
+     * [com.braintreepayments.api.paypal.PayPalAccountNonce].
      *
      * @param paymentData [PaymentData] retrieved from directly integrating with Google Play
      * Services through [PaymentsClient.loadPaymentData]
      * @param callback    [GooglePayTokenizeCallback]
      */
-    fun tokenize(paymentData: PaymentData, callback: GooglePayTokenizeCallback) {
+    fun tokenize(
+        paymentData: PaymentData,
+        callback: GooglePayTokenizeCallback
+    ) {
         val result = tokenize(paymentData)
         when (result) {
             is GooglePayResult.Success -> callbackTokenizeSuccess(result, callback)
@@ -258,7 +304,7 @@ class GooglePayClient internal constructor(
         return try {
             val result = JSONObject(paymentData.toJson())
             GooglePayResult.Success(fromJSON(result))
-        } catch (e: JSONException) {
+        } catch (_: JSONException) {
             try {
                 val token =
                     JSONObject(paymentData.toJson()).getJSONObject("paymentMethodData")
@@ -267,7 +313,7 @@ class GooglePayClient internal constructor(
             } catch (e: Exception) {
                 GooglePayResult.Failure(e)
             }
-        } catch (e: NullPointerException) {
+        } catch (_: NullPointerException) {
             try {
                 val token =
                     JSONObject(paymentData.toJson()).getJSONObject("paymentMethodData")
@@ -283,7 +329,7 @@ class GooglePayClient internal constructor(
      * After a user successfully authorizes Google Pay payment via
      * [GooglePayClient.createPaymentAuthRequest], this
      * method should be invoked to tokenize the payment method to retrieve a
-     * [PaymentMethodNonce]
+     * [com.braintreepayments.api.core.PaymentMethodNonce]
      *
      * @param paymentAuthResult the result of [GooglePayLauncher.launch]
      * @param callback        [GooglePayTokenizeCallback]
@@ -335,7 +381,7 @@ class GooglePayClient internal constructor(
 
         val version = try {
             metadata.getString("version")
-        } catch (e: JSONException) {
+        } catch (_: JSONException) {
             com.braintreepayments.api.core.BuildConfig.VERSION_NAME
         }
 
@@ -440,7 +486,7 @@ class GooglePayClient internal constructor(
                         .put("phoneNumberRequired", request.isPhoneNumberRequired)
                 )
             }
-        } catch (ignored: JSONException) {
+        } catch (_: JSONException) {
         }
         return defaultParameters
     }
@@ -462,7 +508,7 @@ class GooglePayClient internal constructor(
             )
 
             defaultParameters.put("purchase_context", purchaseContext)
-        } catch (ignored: JSONException) {
+        } catch (_: JSONException) {
         }
 
         return defaultParameters
@@ -495,12 +541,12 @@ class GooglePayClient internal constructor(
                     configuration.googlePayAuthorizationFingerprint
                 parameters.put("braintree:authorizationFingerprint", googlePayAuthFingerprint)
             }
-        } catch (ignored: JSONException) {
+        } catch (_: JSONException) {
         }
 
         try {
             cardJson.put("type", "PAYMENT_GATEWAY").put("parameters", parameters)
-        } catch (ignored: JSONException) {
+        } catch (_: JSONException) {
         }
 
         return cardJson
@@ -528,7 +574,7 @@ class GooglePayClient internal constructor(
                             .put("platform", "android").toString()
                     )
             )
-        } catch (ignored: JSONException) {
+        } catch (_: JSONException) {
         }
 
         return json

LocalPayment/src/main/java/com/braintreepayments/api/localpayment/LocalPaymentClient.kt

@@ -58,7 +58,7 @@ class LocalPaymentClient internal constructor(
      * [LocalPaymentAuthRequestParams] on success that should be used to launch the user
      * authentication flow.
      *
-     * @param request  [LocalPaymentRequest] with the payment details.
+     * @param request [LocalPaymentRequest] with the payment details.
      * @param callback [LocalPaymentAuthCallback]
      */
     fun createPaymentAuthRequest(
@@ -71,7 +71,15 @@ class LocalPaymentClient internal constructor(
         }
     }
 
-    private suspend fun createPaymentAuthRequest(
+    /**
+     * Starts the payment flow for a [LocalPaymentRequest] and returns a
+     * [LocalPaymentAuthRequest] on success that should be used to launch the user
+     * authentication flow.
+     *
+     * @param request [LocalPaymentRequest] with the payment details.
+     * @return [LocalPaymentAuthRequest] that can be used to launch the user authentication flow.
+     */
+    suspend fun createPaymentAuthRequest(
         request: LocalPaymentRequest,
     ): LocalPaymentAuthRequest {
         analyticsParamRepository.reset()
@@ -133,7 +141,7 @@ class LocalPaymentClient internal constructor(
                     .put("payment-type", localPaymentAuthRequestParams.request.paymentType)
                     .put("has-user-location-consent", hasUserLocationConsent)
             )
-        } catch (e: JSONException) {
+        } catch (_: JSONException) {
             return authRequestFailure(
                 BraintreeException("Error parsing local payment request")
             )
@@ -174,7 +182,18 @@ class LocalPaymentClient internal constructor(
         }
     }
 
-    private suspend fun tokenize(
+    /**
+     * After receiving a result from the web authentication flow via
+     * [LocalPaymentLauncher.handleReturnToApp], pass the
+     * [LocalPaymentAuthResult.Success] returned to this method to tokenize the local
+     * payment method and receive a [LocalPaymentNonce] on success.
+     *
+     * @param context Android Context
+     * @param localPaymentAuthResult a [LocalPaymentAuthResult.Success] received from
+     * [LocalPaymentLauncher.handleReturnToApp]
+     * @return [LocalPaymentResult]
+     */
+    suspend fun tokenize(
         context: Context,
         localPaymentAuthResult: LocalPaymentAuthResult.Success,
     ): LocalPaymentResult {