From cdce8163ae20ad607c8841be4c10b58c711a709c Mon Sep 17 00:00:00 2001 From: kimberleehowley Date: Tue, 9 Jan 2024 15:43:52 -0800 Subject: [PATCH 1/6] Update comments for ForageSDK.kt --- .../joinforage/forage/android/ForageSDK.kt | 82 ++++++++++--------- 1 file changed, 43 insertions(+), 39 deletions(-) diff --git a/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt b/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt index cf0be857..fc84ddb3 100644 --- a/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt +++ b/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt @@ -21,15 +21,22 @@ import com.joinforage.forage.android.ui.ForageConfig import java.util.UUID /** - * A class implementation of ForageSDKInterface + * An instance of the ForageSDK */ class ForageSDK : ForageSDKInterface { + /** + * Retrieves the ForageConfig for a given ForageElement, or throws an exception if the ForageConfig is not set. + * + * @param element A ForageElement instance + * @return The ForageConfig associated with the ForageElement + * @throws ForageConfigNotSetException If the ForageConfig is not set for the ForageElement + */ private fun _getForageConfigOrThrow(element: AbstractForageElement): ForageConfig { val context = element.getForageConfig() return context ?: throw ForageConfigNotSetException( """ - The ForageElement you passed did have a ForageConfig. In order to submit + The ForageElement you passed did not have a ForageConfig. In order to submit a request via Forage SDK, your ForageElement MUST have a ForageConfig. Make sure to call myForageElement.setForageConfig(forageConfig: ForageConfig) immediately on your ForageElement @@ -38,18 +45,15 @@ class ForageSDK : ForageSDKInterface { } /** - * A method to securely tokenize an EBT card via ForagePANEditText + * Tokenizes an EBT Card via a [ForagePANEditText][com.joinforage.forage.android.ui.ForagePANEditText] Element. * - * @param params The parameters required for tokenization, including - * reference to a ForagePANEditText view for card input. + * @param TokenizeEBTCardParams A model that passes a [`foragePanEditText`][com.joinforage.forage.android.ui.ForagePANEditText] instance, `customerId`, and `reusable` as the [TokenizeEBTCardParams] that Forage uses to tokenize an EBT Card. + * @return A [ForageApiResponse] object. * - * @return A ForageAPIResponse indicating the success or failure of the operation. - * On success, returns a [PaymentMethod](https://docs.joinforage.app/reference/create-payment-method) - * token which can be securely stored and used for subsequent transactions. On failure, - * returns a detailed error response for proper handling. + * On success, the object includes a `ref` token that represents an instance of a Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods#paymentmethod-object). You can store the token for future transactions, like to [`checkBalance`](checkBalance) or to [create a `Payment`](https://docs.joinforage.app/reference/create-a-payment) in Forage's database. * - * @throws ForageConfigNotSetException If the passed ForagePANEditText instance - * hasn't had its ForageConfig set via .setForageConfig(). + * On failure, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. + * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePanEditText`. */ override suspend fun tokenizeEBTCard(params: TokenizeEBTCardParams): ForageApiResponse { val (foragePanEditText, customerId, reusable) = params @@ -83,17 +87,15 @@ class ForageSDK : ForageSDKInterface { } /** - * Checks the balance of a given PaymentMethod using a ForagePINEditText - * - * @param params The parameters required for balance inquiries, including - * a reference to a ForagePINEditText and PaymentMethod ref + * Checks the balance of an EBT Card via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element. * - * @return A ForageAPIResponse indicating the success or failure of the operation. - * On success, returns an object with `snap` (SNAP) and `cash` (EBT Cash) fields, whose values - * indicate the current balance of each respective tender - * - * @throws ForageConfigNotSetException If the passed ForagePINEditText instance - * hasn't had its ForageConfig set via .setForageConfig(). + * @param CheckBalanceParams A model that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a `paymentMethodRef`, found in the response from a call to [tokenizeEBTCard] or the [Create a `PaymentMethod`](https://docs.joinforage.app/reference/create-payment-method) endpoint, as the [CheckBalanceParams] that Forage uses to check the balance of an EBT Card. + * @return A [ForageApiResponse] object. + * + * On success, the object includes `snap` and `cash` fields that indicate the EBT Card's current SNAP and EBT Cash balances. + * + * On failure, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. + * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePinEditText`. */ override suspend fun checkBalance(params: CheckBalanceParams): ForageApiResponse { val (foragePinEditText, paymentMethodRef) = params @@ -171,17 +173,15 @@ class ForageSDK : ForageSDKInterface { } /** - * Captures a Forage Payment associated with an EBT card - * - * @param params The parameters required for payment capture, including - * reference to a ForagePINEditText and a Payment ref + * Captures a payment via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element. * - * @return A ForageAPIResponse indicating the success or failure of the - * payment capture. On success, returns a confirmation of the transaction. - * On failure, provides a detailed error response. - * - * @throws ForageConfigNotSetException If the passed ForagePANEditText instance - * hasn't had its ForageConfig set via .setForageConfig(). + * @param CapturePaymentParams A model that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a `paymentRef`, returned by the [Create a Payment](https://docs.joinforage.app/reference/create-a-payment) endpoint, as the [CapturePaymentParams] that Forage uses to capture a payment. + * @return A [ForageApiResponse] object. + * + * On success, the object confirms the transaction. + * + * On failure, the object includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. + * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePinEditText`. */ override suspend fun capturePayment(params: CapturePaymentParams): ForageApiResponse { val (foragePinEditText, paymentRef) = params @@ -269,17 +269,21 @@ class ForageSDK : ForageSDKInterface { } /** - * Capture a customer's PIN for an EBT payment and defer the capture of the payment to the server + * Submits a customer's PIN via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element and defers payment capture to the server. + * + * @param DeferPaymentCaptureParams A model that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a `paymentRef`, returned by the [Create a Payment](https://docs.joinforage.app/reference/create-a-payment) endpoint, as the [DeferPaymentCaptureParams]. * - * @param params The parameters required for pin capture, including - * reference to a ForagePINEditText and a Payment ref + * @return A [ForageApiResponse] object. + * + * On success, the object returns `Nothing`. + * + * On failure, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. + * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePinEditText`. * - * @return A ForageAPIResponse indicating the success or failure of the - * PIN capture. On success, returns `Nothing`. - * On failure, provides a detailed error response. + * @see + * [Defer EBT payment capture to the server](https://docs.joinforage.app/docs/capture-ebt-payments-server-side) for the related step-by-step guide. * - * @throws ForageConfigNotSetException If the passed ForagePINEditText instance - * hasn't had its ForageConfig set via .setForageConfig(). + * [Capture an EBT Payment](https://docs.joinforage.app/reference/capture-a-payment) for the related endpoint. */ override suspend fun deferPaymentCapture(params: DeferPaymentCaptureParams): ForageApiResponse { val (foragePinEditText, paymentRef) = params From b60df6bb0d58355468d33ac9dec2c12d1ccb890c Mon Sep 17 00:00:00 2001 From: kimberleehowley Date: Thu, 11 Jan 2024 16:06:49 -0800 Subject: [PATCH 2/6] Address PR feedback --- .../joinforage/forage/android/ForageSDK.kt | 60 +++++++++---------- 1 file changed, 28 insertions(+), 32 deletions(-) diff --git a/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt b/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt index fc84ddb3..60a3ff94 100644 --- a/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt +++ b/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt @@ -21,7 +21,16 @@ import com.joinforage.forage.android.ui.ForageConfig import java.util.UUID /** - * An instance of the ForageSDK + * Entry point to the Forage SDK. + * + * A [ForageSDK] instance interacts with the Forage API. + * + * You need an instance of the ForageSDK to perform operations like: + * + * * [capturePayment] + * * [checkBalance] + * * [deferPaymentCapture] + * * [tokenizeEBTCard] */ class ForageSDK : ForageSDKInterface { @@ -47,13 +56,10 @@ class ForageSDK : ForageSDKInterface { /** * Tokenizes an EBT Card via a [ForagePANEditText][com.joinforage.forage.android.ui.ForagePANEditText] Element. * - * @param TokenizeEBTCardParams A model that passes a [`foragePanEditText`][com.joinforage.forage.android.ui.ForagePANEditText] instance, `customerId`, and `reusable` as the [TokenizeEBTCardParams] that Forage uses to tokenize an EBT Card. - * @return A [ForageApiResponse] object. - * - * On success, the object includes a `ref` token that represents an instance of a Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods#paymentmethod-object). You can store the token for future transactions, like to [`checkBalance`](checkBalance) or to [create a `Payment`](https://docs.joinforage.app/reference/create-a-payment) in Forage's database. - * - * On failure, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. + * @param TokenizeEBTCardParams A model that passes a [`foragePanEditText`][com.joinforage.forage.android.ui.ForagePANEditText] instance, `customerId`, and `reusable` boolean as the [TokenizeEBTCardParams] that Forage uses to tokenize an EBT Card. * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePanEditText`. + * @see * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information on error handling + * @return A [ForageApiResponse] object. On success, the object includes a `ref` token that represents an instance of a Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods#paymentmethod-object). You can store the token for future transactions, like to [`checkBalance`](checkBalance) or to [create a `Payment`](https://docs.joinforage.app/reference/create-a-payment) in Forage's database. On failure, for example in the case of [`card_not_reusable`](https://docs.joinforage.app/reference/errors#card_not_reusable) or [`ebt_error_51`](https://docs.joinforage.app/reference/errors#ebt_error_51) errors, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. */ override suspend fun tokenizeEBTCard(params: TokenizeEBTCardParams): ForageApiResponse { val (foragePanEditText, customerId, reusable) = params @@ -87,15 +93,13 @@ class ForageSDK : ForageSDKInterface { } /** - * Checks the balance of an EBT Card via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element. + * Checks the balance of a previously created [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods) via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element. * - * @param CheckBalanceParams A model that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a `paymentMethodRef`, found in the response from a call to [tokenizeEBTCard] or the [Create a `PaymentMethod`](https://docs.joinforage.app/reference/create-payment-method) endpoint, as the [CheckBalanceParams] that Forage uses to check the balance of an EBT Card. - * @return A [ForageApiResponse] object. - * - * On success, the object includes `snap` and `cash` fields that indicate the EBT Card's current SNAP and EBT Cash balances. - * - * On failure, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. + * @param CheckBalanceParams A model that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a `paymentMethodRef`, found in the response from a call to [tokenizeEBTCard] or the [Create a `PaymentMethod`](https://docs.joinforage.app/reference/create-payment-method) endpoint, as the [CheckBalanceParams]. * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePinEditText`. + * @see * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information on error handling. + * * [Test EBT Cards](https://docs.joinforage.app/docs/test-ebt-cards#balance-inquiry-exceptions) to trigger balance inquiry exceptions during testing. + * @return A [ForageApiResponse] object. On success, the object includes `snap` and `cash` fields that indicate the EBT Card's current SNAP and EBT Cash balances. On failure, for example in the case of [`card_not_reusable`](https://docs.joinforage.app/reference/errors#card_not_reusable) or [`ebt_error_51`](https://docs.joinforage.app/reference/errors#ebt_error_51) errors, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. */ override suspend fun checkBalance(params: CheckBalanceParams): ForageApiResponse { val (foragePinEditText, paymentMethodRef) = params @@ -173,15 +177,13 @@ class ForageSDK : ForageSDKInterface { } /** - * Captures a payment via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element. + * Immediately captures a payment via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element. * - * @param CapturePaymentParams A model that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a `paymentRef`, returned by the [Create a Payment](https://docs.joinforage.app/reference/create-a-payment) endpoint, as the [CapturePaymentParams] that Forage uses to capture a payment. - * @return A [ForageApiResponse] object. - * - * On success, the object confirms the transaction. - * - * On failure, the object includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. + * @param CapturePaymentParams A model that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a `paymentRef`, returned by the [Create a Payment](https://docs.joinforage.app/reference/create-a-payment) endpoint, as the [CapturePaymentParams] that Forage uses to capture a payment. * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePinEditText`. + * @see * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information on error handling. + * * [Test EBT Cards](https://docs.joinforage.app/docs/test-ebt-cards#payment-capture-exceptions) to trigger payment capture exceptions during testing. + * @return A [ForageApiResponse] object. On success, the object confirms the transaction. The response includes a Forage [`Payment`](https://docs.joinforage.app/reference/payments) object. On failure, for example in the case of [`card_not_reusable`](https://docs.joinforage.app/reference/errors#card_not_reusable) or [`ebt_error_51`](https://docs.joinforage.app/reference/errors#ebt_error_51) errors, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. */ override suspend fun capturePayment(params: CapturePaymentParams): ForageApiResponse { val (foragePinEditText, paymentRef) = params @@ -273,17 +275,11 @@ class ForageSDK : ForageSDKInterface { * * @param DeferPaymentCaptureParams A model that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a `paymentRef`, returned by the [Create a Payment](https://docs.joinforage.app/reference/create-a-payment) endpoint, as the [DeferPaymentCaptureParams]. * - * @return A [ForageApiResponse] object. - * - * On success, the object returns `Nothing`. - * - * On failure, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. - * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePinEditText`. - * - * @see - * [Defer EBT payment capture to the server](https://docs.joinforage.app/docs/capture-ebt-payments-server-side) for the related step-by-step guide. - * - * [Capture an EBT Payment](https://docs.joinforage.app/reference/capture-a-payment) for the related endpoint. + * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePinEditText`. + * @see * [Defer EBT payment capture to the server](https://docs.joinforage.app/docs/capture-ebt-payments-server-side) for the related step-by-step guide. + * * [Capture an EBT Payment](https://docs.joinforage.app/reference/capture-a-payment) for the API endpoint to call after [deferPaymentCapture]. + * * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information on error handling. + * @return A [ForageApiResponse] object. On success, the object returns `Nothing`. On failure, for example in the case of [`card_not_reusable`](https://docs.joinforage.app/reference/errors#card_not_reusable) or [`ebt_error_51`](https://docs.joinforage.app/reference/errors#ebt_error_51) errors, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. */ override suspend fun deferPaymentCapture(params: DeferPaymentCaptureParams): ForageApiResponse { val (foragePinEditText, paymentRef) = params From e54947e78b1c7c39b9e44ca70f5dd0dbb09c41eb Mon Sep 17 00:00:00 2001 From: kimberleehowley Date: Fri, 12 Jan 2024 11:12:59 -0800 Subject: [PATCH 3/6] Update example ebt error --- .../src/main/java/com/joinforage/forage/android/ForageSDK.kt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt b/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt index 60a3ff94..e9fa55e2 100644 --- a/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt +++ b/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt @@ -59,7 +59,7 @@ class ForageSDK : ForageSDKInterface { * @param TokenizeEBTCardParams A model that passes a [`foragePanEditText`][com.joinforage.forage.android.ui.ForagePANEditText] instance, `customerId`, and `reusable` boolean as the [TokenizeEBTCardParams] that Forage uses to tokenize an EBT Card. * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePanEditText`. * @see * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information on error handling - * @return A [ForageApiResponse] object. On success, the object includes a `ref` token that represents an instance of a Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods#paymentmethod-object). You can store the token for future transactions, like to [`checkBalance`](checkBalance) or to [create a `Payment`](https://docs.joinforage.app/reference/create-a-payment) in Forage's database. On failure, for example in the case of [`card_not_reusable`](https://docs.joinforage.app/reference/errors#card_not_reusable) or [`ebt_error_51`](https://docs.joinforage.app/reference/errors#ebt_error_51) errors, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. + * @return A [ForageApiResponse] object. On success, the object includes a `ref` token that represents an instance of a Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods#paymentmethod-object). You can store the token for future transactions, like to [`checkBalance`](checkBalance) or to [create a `Payment`](https://docs.joinforage.app/reference/create-a-payment) in Forage's database. On failure, for example in the case of [`ebt_error_14`](https://docs.joinforage.app/reference/errors#ebt_error_14), the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. */ override suspend fun tokenizeEBTCard(params: TokenizeEBTCardParams): ForageApiResponse { val (foragePanEditText, customerId, reusable) = params @@ -99,7 +99,7 @@ class ForageSDK : ForageSDKInterface { * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePinEditText`. * @see * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information on error handling. * * [Test EBT Cards](https://docs.joinforage.app/docs/test-ebt-cards#balance-inquiry-exceptions) to trigger balance inquiry exceptions during testing. - * @return A [ForageApiResponse] object. On success, the object includes `snap` and `cash` fields that indicate the EBT Card's current SNAP and EBT Cash balances. On failure, for example in the case of [`card_not_reusable`](https://docs.joinforage.app/reference/errors#card_not_reusable) or [`ebt_error_51`](https://docs.joinforage.app/reference/errors#ebt_error_51) errors, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. + * @return A [ForageApiResponse] object. On success, the object includes `snap` and `cash` fields that indicate the EBT Card's current SNAP and EBT Cash balances. On failure, for example in the case of [`ebt_error_14`](https://docs.joinforage.app/reference/errors#ebt_error_14), the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. */ override suspend fun checkBalance(params: CheckBalanceParams): ForageApiResponse { val (foragePinEditText, paymentMethodRef) = params From 8e9dae1dd942acdbc2da25676a099ded6d93c9e5 Mon Sep 17 00:00:00 2001 From: kimberleehowley Date: Fri, 12 Jan 2024 16:09:14 -0800 Subject: [PATCH 4/6] Add PR feedback --- .../joinforage/forage/android/ForageSDK.kt | 129 ++++++++++++++---- 1 file changed, 100 insertions(+), 29 deletions(-) diff --git a/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt b/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt index e9fa55e2..3a75988c 100644 --- a/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt +++ b/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt @@ -27,15 +27,17 @@ import java.util.UUID * * You need an instance of the ForageSDK to perform operations like: * - * * [capturePayment] - * * [checkBalance] - * * [deferPaymentCapture] - * * [tokenizeEBTCard] + * * [Tokenize card information][tokenizeEBTCard] + * * [Check the balance of a card][checkBalance] + * * [Collect a customer's card PIN for a payment and defer + * the capture of the payment to the server][deferPaymentCapture] + * * [Capture a payment immediately][capturePayment] */ class ForageSDK : ForageSDKInterface { /** - * Retrieves the ForageConfig for a given ForageElement, or throws an exception if the ForageConfig is not set. + * Retrieves the ForageConfig for a given ForageElement, or throws an exception if the + * ForageConfig is not set. * * @param element A ForageElement instance * @return The ForageConfig associated with the ForageElement @@ -54,12 +56,27 @@ class ForageSDK : ForageSDKInterface { } /** - * Tokenizes an EBT Card via a [ForagePANEditText][com.joinforage.forage.android.ui.ForagePANEditText] Element. + * Tokenizes an EBT Card via a [ForagePANEdit + * Text][com.joinforage.forage.android.ui.ForagePANEditText] Element. * - * @param TokenizeEBTCardParams A model that passes a [`foragePanEditText`][com.joinforage.forage.android.ui.ForagePANEditText] instance, `customerId`, and `reusable` boolean as the [TokenizeEBTCardParams] that Forage uses to tokenize an EBT Card. - * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePanEditText`. - * @see * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information on error handling - * @return A [ForageApiResponse] object. On success, the object includes a `ref` token that represents an instance of a Forage [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods#paymentmethod-object). You can store the token for future transactions, like to [`checkBalance`](checkBalance) or to [create a `Payment`](https://docs.joinforage.app/reference/create-a-payment) in Forage's database. On failure, for example in the case of [`ebt_error_14`](https://docs.joinforage.app/reference/errors#ebt_error_14), the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. + * * On success, the object includes a `ref` token that represents an instance of a Forage + * [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods#paymentmethod-object). + * You can store the token for future transactions, like to [`checkBalance`](checkBalance) or + * to [create a `Payment`](https://docs.joinforage.app/reference/create-a-payment) in + * Forage's database. + * * On failure, for example in the case of + * [`ebt_error_14`](https://docs.joinforage.app/reference/errors#ebt_error_14), + * the response includes a list of + * [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can + * unpack to troubleshoot the issue. + * @param params A [TokenizeEBTCardParams] model that passes a [`foragePanEditText`] + * [com.joinforage.forage.android.ui.ForagePANEditText] instance, a `customerId`, and a `reusable` + * boolean that Forage uses to tokenize an EBT Card. + * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided + * `foragePanEditText`. + * @see * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more + * information on error handling. + * @return A [ForageApiResponse] object. */ override suspend fun tokenizeEBTCard(params: TokenizeEBTCardParams): ForageApiResponse { val (foragePanEditText, customerId, reusable) = params @@ -93,13 +110,30 @@ class ForageSDK : ForageSDKInterface { } /** - * Checks the balance of a previously created [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods) via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element. + * Checks the balance of a previously created + * [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods) + * via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element. * - * @param CheckBalanceParams A model that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a `paymentMethodRef`, found in the response from a call to [tokenizeEBTCard] or the [Create a `PaymentMethod`](https://docs.joinforage.app/reference/create-payment-method) endpoint, as the [CheckBalanceParams]. - * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePinEditText`. - * @see * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information on error handling. - * * [Test EBT Cards](https://docs.joinforage.app/docs/test-ebt-cards#balance-inquiry-exceptions) to trigger balance inquiry exceptions during testing. - * @return A [ForageApiResponse] object. On success, the object includes `snap` and `cash` fields that indicate the EBT Card's current SNAP and EBT Cash balances. On failure, for example in the case of [`ebt_error_14`](https://docs.joinforage.app/reference/errors#ebt_error_14), the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. + * * On success, the response object includes `snap` and `cash` fields that indicate + * the EBT Card's current SNAP and EBT Cash balances. + * * On failure, for example in the case of + * [`ebt_error_14`](https://docs.joinforage.app/reference/errors#ebt_error_14), + * the response includes a list of + * [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can + * unpack to troubleshoot the issue. + * @param params A [CheckBalanceParams] model that passes + * a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a + * `paymentMethodRef`, found in the response from a call to [tokenizeEBTCard] or the + * [Create a `PaymentMethod`](https://docs.joinforage.app/reference/create-payment-method) + * endpoint, that Forage uses to check the payment method's balance. + * + * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided + * `foragePinEditText`. + * @see * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more + * information on error handling. + * * [Test EBT Cards](https://docs.joinforage.app/docs/test-ebt-cards#balance-inquiry-exceptions) + * to trigger balance inquiry exceptions during testing. + * @return A [ForageApiResponse] object. */ override suspend fun checkBalance(params: CheckBalanceParams): ForageApiResponse { val (foragePinEditText, paymentMethodRef) = params @@ -177,13 +211,32 @@ class ForageSDK : ForageSDKInterface { } /** - * Immediately captures a payment via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element. + * Immediately captures a payment via a + * [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element. + * + * * On success, the object confirms the transaction. The response includes a Forage + * [`Payment`](https://docs.joinforage.app/reference/payments) object. + * * On failure, for example in the case of + * [`card_not_reusable`](https://docs.joinforage.app/reference/errors#card_not_reusable) or + * [`ebt_error_51`](https://docs.joinforage.app/reference/errors#ebt_error_51) errors, the + * response includes a list of + * [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can + * unpack to troubleshoot the issue. * - * @param CapturePaymentParams A model that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a `paymentRef`, returned by the [Create a Payment](https://docs.joinforage.app/reference/create-a-payment) endpoint, as the [CapturePaymentParams] that Forage uses to capture a payment. - * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePinEditText`. - * @see * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information on error handling. - * * [Test EBT Cards](https://docs.joinforage.app/docs/test-ebt-cards#payment-capture-exceptions) to trigger payment capture exceptions during testing. - * @return A [ForageApiResponse] object. On success, the object confirms the transaction. The response includes a Forage [`Payment`](https://docs.joinforage.app/reference/payments) object. On failure, for example in the case of [`card_not_reusable`](https://docs.joinforage.app/reference/errors#card_not_reusable) or [`ebt_error_51`](https://docs.joinforage.app/reference/errors#ebt_error_51) errors, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. + * @param params A [CapturePaymentParams] model that passes a + * [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] + * instance and a `paymentRef`, returned by the + * [Create a Payment](https://docs.joinforage.app/reference/create-a-payment) endpoint, that + * Forage uses to capture a payment. + * + * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided + * `foragePinEditText`. + * @see + * * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information + * on error handling. + * * [Test EBT Cards](https://docs.joinforage.app/docs/test-ebt-cards#payment-capture-exceptions) + * to trigger payment capture exceptions during testing. + * @return A [ForageApiResponse] object. */ override suspend fun capturePayment(params: CapturePaymentParams): ForageApiResponse { val (foragePinEditText, paymentRef) = params @@ -271,15 +324,33 @@ class ForageSDK : ForageSDKInterface { } /** - * Submits a customer's PIN via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element and defers payment capture to the server. + * Submits a customer's PIN via a + * [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element and defers + * payment capture to the server. + * + * * On success, the object returns `Nothing`. + * * On failure, for example in the case of + * [`card_not_reusable`](https://docs.joinforage.app/reference/errors#card_not_reusable) + * or [`ebt_error_51`](https://docs.joinforage.app/reference/errors#ebt_error_51) errors, the + * response includes a list of + * [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can + * unpack to troubleshoot the issue. * - * @param DeferPaymentCaptureParams A model that passes a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a `paymentRef`, returned by the [Create a Payment](https://docs.joinforage.app/reference/create-a-payment) endpoint, as the [DeferPaymentCaptureParams]. + * @param params A [DeferPaymentCaptureParams] model that passes a + * [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a + * `paymentRef`, returned by the + * [Create a Payment](https://docs.joinforage.app/reference/create-a-payment) endpoint, as the + * DeferPaymentCaptureParams. * - * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided `foragePinEditText`. - * @see * [Defer EBT payment capture to the server](https://docs.joinforage.app/docs/capture-ebt-payments-server-side) for the related step-by-step guide. - * * [Capture an EBT Payment](https://docs.joinforage.app/reference/capture-a-payment) for the API endpoint to call after [deferPaymentCapture]. - * * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information on error handling. - * @return A [ForageApiResponse] object. On success, the object returns `Nothing`. On failure, for example in the case of [`card_not_reusable`](https://docs.joinforage.app/reference/errors#card_not_reusable) or [`ebt_error_51`](https://docs.joinforage.app/reference/errors#ebt_error_51) errors, the response includes a list of [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can unpack to troubleshoot the issue. + * @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided + * `foragePinEditText`. + * @see * [Defer EBT payment capture to the server](https://docs.joinforage.app/docs/capture-ebt-payments-server-side) + * for the related step-by-step guide. + * * [Capture an EBT Payment](https://docs.joinforage.app/reference/capture-a-payment) + * for the API endpoint to call after [deferPaymentCapture]. + * * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information + * on error handling. + * @return A [ForageApiResponse] object. */ override suspend fun deferPaymentCapture(params: DeferPaymentCaptureParams): ForageApiResponse { val (foragePinEditText, paymentRef) = params From 30a920c6aed8154ce3e14ecd04f0b4ffe9a0672d Mon Sep 17 00:00:00 2001 From: kimberleehowley Date: Fri, 12 Jan 2024 16:30:48 -0800 Subject: [PATCH 5/6] Attempt to fix linting --- .../src/main/java/com/joinforage/forage/android/ForageSDK.kt | 1 - 1 file changed, 1 deletion(-) diff --git a/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt b/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt index 3b4f35d1..0f4d4d2a 100644 --- a/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt +++ b/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt @@ -34,7 +34,6 @@ import com.joinforage.forage.android.ui.ForagePINEditText * * [Capture a payment immediately][capturePayment] */ class ForageSDK : ForageSDKInterface { - /** * Retrieves the ForageConfig for a given ForageElement, or throws an exception if the * ForageConfig is not set. From bdc9211193054217f4058ff702a31007e4573d58 Mon Sep 17 00:00:00 2001 From: kimberleehowley Date: Tue, 16 Jan 2024 14:16:36 -0800 Subject: [PATCH 6/6] Typo --- .../main/java/com/joinforage/forage/android/ForageSDK.kt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt b/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt index 0f4d4d2a..a524b83c 100644 --- a/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt +++ b/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt @@ -27,11 +27,11 @@ import com.joinforage.forage.android.ui.ForagePINEditText * * You need an instance of the ForageSDK to perform operations like: * - * * [Tokenize card information][tokenizeEBTCard] - * * [Check the balance of a card][checkBalance] - * * [Collect a customer's card PIN for a payment and defer + * * [Tokenizing card information][tokenizeEBTCard] + * * [Checking the balance of a card][checkBalance] + * * [Collecting a customer's card PIN for a payment and deferring * the capture of the payment to the server][deferPaymentCapture] - * * [Capture a payment immediately][capturePayment] + * * [Capturing a payment immediately][capturePayment] */ class ForageSDK : ForageSDKInterface { /**