Add Javadocs for Non-Ui payment callbacks

Author: jeremiahAI

rave_presentation/src/main/java/com/flutterwave/raveandroid/rave_presentation/account/AccountPaymentCallback.java

@@ -1,23 +1,71 @@
 package com.flutterwave.raveandroid.rave_presentation.account;
 
+import android.webkit.WebResourceRequest;
+import android.webkit.WebView;
+
 import androidx.annotation.Nullable;
 
 import com.flutterwave.raveandroid.rave_core.models.Bank;
 
 import java.util.List;
 
 public interface AccountPaymentCallback {
+    /**
+     * Passes a list of banks available for this payment method.
+     *
+     * @param banks List of banks.
+     */
     void onBanksListRetrieved(List<Bank> banks);
 
+    /**
+     * Called when there is an issue retrieving the list of banks.
+     *
+     * @param message
+     */
     void onGetBanksRequestFailed(String message);
 
+    /**
+     * Called to indicate that a background task is running, e.g. a network call.
+     * This should typically show or hide a progress bar.
+     *
+     * @param active If true, background task is running. If false, background task has stopped
+     */
     void showProgressIndicator(boolean active);
 
+    /**
+     * Called to trigger an otp collection. The OTP should be collected from the user and passed to
+     * the PaymentManager using {@link AccountPaymentManager#submitOtp(String)} to continue the payment.
+     */
     void collectOtp(String message);
 
+    /**
+     * Called to display a {@link android.webkit.WebView} for charges that require webpage authentication.
+     * When the payment is completed, the authentication page redirects to a {@link com.flutterwave.raveandroid.rave_java_commons.RaveConstants#RAVE_3DS_CALLBACK predefined url}
+     * with the payment details appended to the url.
+     * <p>
+     * You should override the webview client's {@link android.webkit.WebViewClient#shouldOverrideUrlLoading(WebView, WebResourceRequest)} shouldOverrideUrlLoading}
+     * function to check if the {@link WebResourceRequest#getUrl() url being loaded} contains the
+     * {@link com.flutterwave.raveandroid.rave_java_commons.RaveConstants#RAVE_3DS_CALLBACK predefined redirect url}.
+     * <p>
+     * If it does, it means the transaction has been completed and you can now call {@link AccountPaymentManager#onWebpageAuthenticationComplete()} to check the transaction status.
+     *
+     * @param authenticationUrl The url to the authentication page
+     */
+    void showAuthenticationWebPage(String authenticationUrl);
+
+    /**
+     * Called when an error occurs with the payment. The error message can be displayed to the users.
+     *
+     * @param errorMessage A message describing the error
+     * @param flwRef       The Flutterwave reference to the transaction.
+     */
     void onError(String errorMessage, @Nullable String flwRef);
 
+    /**
+     * Called when the transaction has been completed successfully.
+     *
+     * @param flwRef The Flutterwave reference to the transaction.
+     */
     void onSuccessful(String flwRef);
 
-    void showAuthenticationWebPage(String authenticationUrl);
 }

rave_presentation/src/main/java/com/flutterwave/raveandroid/rave_presentation/ach/AchPaymentCallback.java

@@ -1,13 +1,47 @@
 package com.flutterwave.raveandroid.rave_presentation.ach;
 
+import android.webkit.WebResourceRequest;
+import android.webkit.WebView;
+
 import androidx.annotation.Nullable;
 
 public interface AchPaymentCallback {
+
+    /**
+     * Called to indicate that a background task is running, e.g. a network call.
+     * This should typically show or hide a progress bar.
+     *
+     * @param active If true, background task is running. If false, background task has stopped
+     */
     void showProgressIndicator(boolean active);
 
+    /**
+     * Called when an error occurs with the payment. The error message can be displayed to the users.
+     *
+     * @param errorMessage A message describing the error
+     * @param flwRef       The Flutterwave reference to the transaction.
+     */
     void onError(String errorMessage, @Nullable String flwRef);
 
+    /**
+     * Called when the transaction has been completed successfully.
+     *
+     * @param flwRef The Flutterwave reference to the transaction.
+     */
     void onSuccessful(String flwRef);
 
+    /**
+     * Called to display a {@link android.webkit.WebView} for charges that require webpage authentication.
+     * When the payment is completed, the authentication page redirects to a {@link com.flutterwave.raveandroid.rave_java_commons.RaveConstants#RAVE_3DS_CALLBACK predefined url}
+     * with the payment details appended to the url.
+     * <p>
+     * You should override the webview client's {@link android.webkit.WebViewClient#shouldOverrideUrlLoading(WebView, WebResourceRequest)} shouldOverrideUrlLoading}
+     * function to check if the {@link WebResourceRequest#getUrl() url being loaded} contains the
+     * {@link com.flutterwave.raveandroid.rave_java_commons.RaveConstants#RAVE_3DS_CALLBACK predefined redirect url}.
+     * <p>
+     * If it does, it means the transaction has been completed and you can now call {@link AchPaymentManager#onWebpageAuthenticationComplete()} to check the transaction status.
+     *
+     * @param authenticationUrl The url to the authentication page
+     */
     void showAuthenticationWebPage(String authenticationUrl);
 }

rave_presentation/src/main/java/com/flutterwave/raveandroid/rave_presentation/banktransfer/BankTransferPaymentCallback.java

@@ -3,13 +3,45 @@
 import androidx.annotation.Nullable;
 
 public interface BankTransferPaymentCallback {
+    /**
+     * Called to indicate that a background task is running, e.g. a network call.
+     * This should typically show or hide a progress bar.
+     *
+     * @param active If true, background task is running. If false, background task has stopped
+     */
     void showProgressIndicator(boolean active);
 
+    /**
+     * Called when an error occurs with the payment. The error message can be displayed to the users.
+     *
+     * @param errorMessage A message describing the error
+     * @param flwRef       The Flutterwave reference to the transaction.
+     */
     void onError(String errorMessage, @Nullable String flwRef);
 
+    /**
+     * Called when the transaction has been completed successfully.
+     *
+     * @param flwRef The Flutterwave reference to the transaction.
+     */
     void onSuccessful(String flwRef);
 
+    /**
+     * Passes the details of the bank account to be transferred to. These details should be displayed
+     * to the user for them to make the transfer and complete the transaction. {@link BankTransferPaymentManager#checkTransactionStatus(int)}
+     * should be called after this, or when the user has completed the transfer, to confirm the transaction status.
+     *
+     * @param amount          The amount to be transferred
+     * @param accountNumber   The account number to be transferred to
+     * @param bankName        The name of the bank to be transferred to
+     * @param beneficiaryName The name of the account to be transferred to
+     */
     void onTransferDetailsReceived(String amount, String accountNumber, String bankName, String beneficiaryName);
 
+    /**
+     * Called when the bank transfer has not been confirmed in the timeout when calling {@link BankTransferPaymentManager#checkTransactionStatus(int)}.
+     *
+     * @param flwRef
+     */
     void onPollingTimeout(String flwRef);
 }

rave_presentation/src/main/java/com/flutterwave/raveandroid/rave_presentation/barter/BarterPaymentCallback.java

@@ -3,11 +3,34 @@
 import androidx.annotation.Nullable;
 
 public interface BarterPaymentCallback {
+    /**
+     * Called to indicate that a background task is running, e.g. a network call.
+     * This should typically show or hide a progress bar.
+     *
+     * @param active If true, background task is running. If false, background task has stopped
+     */
     void showProgressIndicator(boolean active);
 
+    /**
+     * Called when an error occurs with the payment. The error message can be displayed to the users.
+     *
+     * @param errorMessage A message describing the error
+     * @param flwRef       The Flutterwave reference to the transaction.
+     */
     void onError(String errorMessage, @Nullable String flwRef);
 
+    /**
+     * Called when the transaction has been completed successfully.
+     *
+     * @param flwRef The Flutterwave reference to the transaction.
+     */
     void onSuccessful(String flwRef);
 
-    void loadBarterCheckout(String authUrlCrude, String flwRef);
+    /**
+     * Called to display a {@link android.webkit.WebView} for webpage authentication.
+     *
+     * @param authenticationUrl The url to the authentication page
+     * @param flwRef            The Flutterwave transaction reference
+     */
+    void loadBarterCheckout(String authenticationUrl, String flwRef);
 }

rave_presentation/src/main/java/com/flutterwave/raveandroid/rave_presentation/barter/NullBarterPaymentCallback.java

@@ -20,7 +20,7 @@ public void onSuccessful(String flwRef) {
     }
 
     @Override
-    public void loadBarterCheckout(String authUrlCrude, String flwRef) {
+    public void loadBarterCheckout(String authenticationUrl, String flwRef) {
 
     }
 }

rave_presentation/src/main/java/com/flutterwave/raveandroid/rave_presentation/card/CardContract.java

@@ -105,7 +105,7 @@ interface CardInteractor {
         void collectCardAddressDetails(Payload payload, String authModel);
 
         /**
-         * Called to display a {@link android.webkit.WebView} for cards that require 3D-Secure authentication.
+         * Called to display a {@link android.webkit.WebView} for charges that require webpage authentication.
          * When the payment is completed, the authentication page redirects to a {@link com.flutterwave.raveandroid.rave_java_commons.RaveConstants#RAVE_3DS_CALLBACK predefined url}
          * with the payment details appended to the url.
          * <p>

rave_presentation/src/main/java/com/flutterwave/raveandroid/rave_presentation/card/CardPaymentCallback.java

@@ -1,19 +1,66 @@
 package com.flutterwave.raveandroid.rave_presentation.card;
 
+import android.webkit.WebResourceRequest;
+import android.webkit.WebView;
+
 import androidx.annotation.Nullable;
 
+import com.flutterwave.raveandroid.rave_presentation.data.AddressDetails;
+
 public interface CardPaymentCallback {
+    /**
+     * Called to indicate that a background task is running, e.g. a network call.
+     * This should typically show or hide a progress bar.
+     *
+     * @param active If true, background task is running. If false, background task has stopped
+     */
     void showProgressIndicator(boolean active);
 
+    /**
+     * Called to trigger a pin collection. The pin should be collected from the user and passed to
+     * the CardPaymentManager using {@link CardPaymentManager#submitPin(String)} to continue the payment.
+     */
     void collectCardPin();
 
+    /**
+     * Called to trigger an otp collection. The OTP should be collected from the user and passed to
+     * the CardPaymentManager using {@link CardPaymentManager#submitOtp(String)} to continue the payment.
+     */
     void collectOtp(String message);
 
-    void onError(String errorMessage, @Nullable String flwRef);
-
-    void onSuccessful(String flwRef);
-
+    /**
+     * Called to trigger address details collection. The address should be collected from the user and passed to
+     * the CardPaymentManager using {@link CardPaymentManager#submitAddress(AddressDetails)} to continue the payment.
+     */
     void collectAddress();
 
+    /**
+     * Called to display a {@link android.webkit.WebView} for charges that require webpage authentication.
+     * When the payment is completed, the authentication page redirects to a {@link com.flutterwave.raveandroid.rave_java_commons.RaveConstants#RAVE_3DS_CALLBACK predefined url}
+     * with the payment details appended to the url.
+     * <p>
+     * You should override the webview client's {@link android.webkit.WebViewClient#shouldOverrideUrlLoading(WebView, WebResourceRequest)} shouldOverrideUrlLoading}
+     * function to check if the {@link WebResourceRequest#getUrl() url being loaded} contains the
+     * {@link com.flutterwave.raveandroid.rave_java_commons.RaveConstants#RAVE_3DS_CALLBACK predefined redirect url}.
+     * <p>
+     * If it does, it means the transaction has been completed and you can now call {@link CardPaymentManager#onWebpageAuthenticationComplete()} to check the transaction status.
+     *
+     * @param authenticationUrl The url to the authentication page
+     */
     void showAuthenticationWebPage(String authenticationUrl);
+
+    /**
+     * Called when an error occurs with the payment. The error message can be displayed to the users.
+     *
+     * @param errorMessage A message describing the error
+     * @param flwRef       The Flutterwave reference to the transaction.
+     */
+    void onError(String errorMessage, @Nullable String flwRef);
+
+    /**
+     * Called when the transaction has been completed successfully.
+     *
+     * @param flwRef The Flutterwave reference to the transaction.
+     */
+    void onSuccessful(String flwRef);
 }

rave_presentation/src/main/java/com/flutterwave/raveandroid/rave_presentation/francmobilemoney/FrancophoneMobileMoneyPaymentCallback.java

@@ -3,9 +3,27 @@
 import androidx.annotation.Nullable;
 
 public interface FrancophoneMobileMoneyPaymentCallback {
+
+    /**
+     * Called to indicate that a background task is running, e.g. a network call.
+     * This should typically show or hide a progress bar.
+     *
+     * @param active If true, background task is running. If false, background task has stopped
+     */
     void showProgressIndicator(boolean active);
 
+    /**
+     * Called when an error occurs with the payment. The error message can be displayed to the users.
+     *
+     * @param errorMessage A message describing the error
+     * @param flwRef       The Flutterwave reference to the transaction.
+     */
     void onError(String errorMessage, @Nullable String flwRef);
 
+    /**
+     * Called when the transaction has been completed successfully.
+     *
+     * @param flwRef The Flutterwave reference to the transaction.
+     */
     void onSuccessful(String flwRef);
 }

rave_presentation/src/main/java/com/flutterwave/raveandroid/rave_presentation/ghmobilemoney/GhanaMobileMoneyPaymentCallback.java

@@ -1,13 +1,46 @@
 package com.flutterwave.raveandroid.rave_presentation.ghmobilemoney;
 
+import android.webkit.WebResourceRequest;
+import android.webkit.WebView;
+
 import androidx.annotation.Nullable;
 
 public interface GhanaMobileMoneyPaymentCallback {
+    /**
+     * Called to indicate that a background task is running, e.g. a network call.
+     * This should typically show or hide a progress bar.
+     *
+     * @param active If true, background task is running. If false, background task has stopped
+     */
     void showProgressIndicator(boolean active);
 
+    /**
+     * Called when an error occurs with the payment. The error message can be displayed to the users.
+     *
+     * @param errorMessage A message describing the error
+     * @param flwRef       The Flutterwave reference to the transaction.
+     */
     void onError(String errorMessage, @Nullable String flwRef);
 
+    /**
+     * Called when the transaction has been completed successfully.
+     *
+     * @param flwRef The Flutterwave reference to the transaction.
+     */
     void onSuccessful(String flwRef);
 
+    /**
+     * Called to display a {@link android.webkit.WebView} for charges that require webpage authentication.
+     * When the payment is completed, the authentication page redirects to a {@link com.flutterwave.raveandroid.rave_java_commons.RaveConstants#RAVE_3DS_CALLBACK predefined url}
+     * with the payment details appended to the url.
+     * <p>
+     * You should override the webview client's {@link android.webkit.WebViewClient#shouldOverrideUrlLoading(WebView, WebResourceRequest)} shouldOverrideUrlLoading}
+     * function to check if the {@link WebResourceRequest#getUrl() url being loaded} contains the
+     * {@link com.flutterwave.raveandroid.rave_java_commons.RaveConstants#RAVE_3DS_CALLBACK predefined redirect url}.
+     * <p>
+     * If it does, it means the transaction has been completed and you can now call {@link GhanaMobileMoneyPaymentManager#onWebpageAuthenticationComplete()} to check the transaction status.
+     *
+     * @param url The url to the authentication page
+     */
     void showAuthenticationWebPage(String url);
 }

rave_presentation/src/main/java/com/flutterwave/raveandroid/rave_presentation/mpesa/MpesaPaymentCallback.java

@@ -3,9 +3,26 @@
 import androidx.annotation.Nullable;
 
 public interface MpesaPaymentCallback {
+    /**
+     * Called to indicate that a background task is running, e.g. a network call.
+     * This should typically show or hide a progress bar.
+     *
+     * @param active If true, background task is running. If false, background task has stopped
+     */
     void showProgressIndicator(boolean active);
 
+    /**
+     * Called when an error occurs with the payment. The error message can be displayed to the users.
+     *
+     * @param errorMessage A message describing the error
+     * @param flwRef       The Flutterwave reference to the transaction.
+     */
     void onError(String errorMessage, @Nullable String flwRef);
 
+    /**
+     * Called when the transaction has been completed successfully.
+     *
+     * @param flwRef The Flutterwave reference to the transaction.
+     */
     void onSuccessful(String flwRef);
 }