Skip to content

CustomUiImplementation.md

Latest commit

 

History

History
271 lines (214 loc) · 13.1 KB

CustomUiImplementation.md

File metadata and controls

271 lines (214 loc) · 13.1 KB

Custom UI Implementation

The Flutterwave SDK can be integrated with your custom UI, allowing you to manage the entire User Interface. This section guides you on how to implement this.

1. Create a RaveNonUIManager instance

Begin by creating an instance of RaveNonUIManager and setting the public and encryption key, along with other required parameters.

    RaveNonUIManager raveNonUIManager =
                    new RaveNonUIManager()
                    .setAmount(amount)
                    .setCurrency(currency)
                    .setEmail(email)
                    .setfName(fName)
                    .setlName(lName)
                    .setNarration(narration)
                    .setPublicKey(publicKey)
                    .setEncryptionKey(encryptionKey)
                    .setTxRef(txRef)
                    .setPhoneNumber(phoneNumber, boolean)
                    .onStagingEnv(boolean)
                    .setMeta(List<Meta>)
                    .isPreAuth(boolean)
                    .setSubAccounts(List<SubAccount>)
                    .shouldDisplayFee(boolean)
                    .showStagingLabel(boolean)
                    .initialize();
Function Definitions
Function Parameter Type Required
setAmount(amount) This sets the amount to be charged from the customer. double Required
setCurrency(currency) This sets the specified currency to charge the customer in. String Required
setfName(fName) This sets the first name of the customer. String Required
setlName(lName) This sets the last name of the customer. String Required
setEmail(email) This sets the email address of the customer. String Required
setNarration(narration) This sets a custom description added by the merchant. For Bank Transfer payments, this will be shown to the customer as the account name when the account number is resolved. String Not Required
setPublicKey(publicKey) This sets the Merchant's public key. Get your live and test public key from your dashboard here. For further information on how to retrieve your keys, visit here. String Required
setEncryptionKey(encryptionKey) This sets the Merchant's encryption key. Get your live and test encryption key from your dashboard here. For further information on how to retrieve your keys, visit here. String Required
setTxRef(txRef) This is the unique reference, specific to the particular transaction being carried out. This should be generated for each transaction. String Required
setPhoneNumber(phoneNumber) This sets the customer's phone number. This function has an overload to specify whether the customer can edit their phone number: setPhoneNumber(phoneNumber, false). When set to false, the customer is unable to change the phone number provided. String

Optional overloads:
String, boolean		 Not Required
onStagingEnv(boolean) Set to true to carry out test transactions in the staging environment; otherwise, the default value
is false. boolean Not Required
setMeta(List<Meta>) Adds custom data to be passed. It accepts a List of Meta objects List Not Required
setSubAccounts(List<SubAccount>) Accepts a List of SubAccount, if you want to split the transaction fee with other accounts. Subaccounts are vendors' accounts to be settled per transaction. To initialize a SubAccount class, use SubAccount(String subAccountId, String transactionSplitRatio) or SubAccount(String subAccountId, String transactionSplitRatio, String transactionChargeType, String transactionCharge) to also charge the subaccount a fee. Learn more about split payments and subaccounts. List<SubAccount> Not Required
setIsPreAuth(boolean) Set to true to preauthorise the transaction amount. Learn more about preauthourization. int Not Required
setPaymentPlan(payment_plan) If you want to set up recurrent payments, this is the payment plan ID to use. For guidance on creating payment plans, visit here. Recurring payment is only available for card payments String Not Required
initialize() Returns the prepared RaveNonUiManager that can be used with any of the payment managers for the different payment methods. N/A Required

2. Initiate a charge

Use the payment method's manager to initiate a charge. For example, to charge cards, use the CardPaymentManager. (Store the Payment Manager object in a variable to be able to access it in the next steps.)

   CardPaymentManager cardPayManager = new CardPaymentManager(
   raveNonUIManager, CardPaymentCallback, SavedCardsListener);
   Card card = new Card(
                    "5531886652142950")
                    "12",
                    "22",
                    "123"
            ); // Test MasterCard PIN

    cardPayManager.chargeCard(card);

3. Implement callbacks

We have predefined callback classes for each payment method. Make your Fragment/Activity (or other class handling the payment interaction) implement the specified callback for the payment method you'd like to use, and override the specified callback functions. For example, to charge cards, implement the CardPaymentCallback.

See Example 
  public class PaymentActivity extends AppCompatActivity implements CardPaymentCallback {

  // Step 1 and Step 2 here...

  // Methods to override for card payment
  @Override
  public void collectCardPin() {
      //collect PIN from User and pass to the CardPayManager object.
      cardPayManager.submitPin(pin);
  }

  @Override
  public void collectOtp(String message) {
      //collect OTP from User and pass to the CardPayManager object.
      cardPayManager.submitOtp(otp);
  }

  @Override
  public void collectAddress() {
      //collect Card Address details from User and pass to the CardPayManager object.
      cardPayManager.submitAddress(address);
  }

  @Override
  public void showAuthenticationWebPage(String authenticationUrl) {
      //Show a Webview for transaction authentication and call the CardPayManager object when the webview authentication is done. 
      // See the JavaDoc for this method for more details.
      
      cardPayManager.onWebpageAuthenticationComplete();
  }

  @Override
  public void onError(String errorMessage, @Nullable String flwRef) {
      // Error during transaction
      Toast.makeText(this, errorMessage, Toast.LENGTH_LONG).show();
  }

  @Override
  public void onSuccessful(String flwRef) {
      // Transaction successful
      Toast.makeText(this, "Transaction Successful", Toast.LENGTH_LONG).show();
  }
}
See All Payment Managers and Callbacks

Payment Methods and corresponding PaymentManager and Callback class names

Payment Method Payment Manager Class Names Payment Callback Class Names
Account (Direct Debit) AccountPaymentManager AccountPaymentCallback
ACH AchPaymentManager AchPaymentCallback
Bank Transfer BankTransferPaymentManager BankTransferPaymentCallback
Barter BarterPaymentManager BarterPaymentCallback
Card CardPaymentManager CardPaymentCallback
Francophone Mobile Money FrancophoneMobileMoneyPaymentManager FrancophoneMobileMoneyPaymentCallback
Ghana Mobile Money GhMobileMoneyPaymentManager GhMobileMoneyPaymentCallback
MPesa MpesaPaymentManager MpesaPaymentCallback
Rwanda Mobile Money RwfMobileMoneyPaymentManager RwfMobileMoneyPaymentCallback
South Africa Bank Account SaBankAccountPaymentManager SaBankAccountPaymentCallback
Uganda Mobile Money UgandaMobileMoneyPaymentManager UgandaMobileMoneyPaymentCallback
UK Bank Payment UkBankPaymentManager UkBankPaymentCallback
USSD UssdPaymentManager UssdPaymentCallback
Zambia Mobile Money ZmMobileMoneyPaymentManager ZmMobileMoneyPaymentCallback

We worked on a module to simplify charge verification when using the No-UI approach. You can read about using it here.

Due to the multiple payment methods available, all the methods of the different payment callback classes could not be documented here. Please refer to the individual Javadocs in the code if clarification is needed.

To see a more practical way of using the SDK, head to our sample app in the repository here.

Configuring ProGuard

To configure ProGuard, add the following lines to your ProGuard configuration file. This will keep files related to this SDK.

keepclasseswithmembers public class com.flutterwave.raveandroid.** { *; }
dontwarn com.flutterwave.raveandroid.card.CardFragment

Extras

Fee checking

If you would like to include fee checks, make your calling class implement the FeeCheckListener, then pass the calling class as an argument to the Payment Manager's fetchTransactionFee() function.

Example 
public class PaymentActivity extends AppCompatActivity
      implements FeeCheckListener // Implement if you want to be able to check fees beforehand
      // Don't forget to implement the payment callback(s) for the payment method(s) you want to use.
{

  //...
  //...
  void fetchFee(){
      // Call the fetch transaction  fee function with `this` as an argument. The overridden callbacks will then be called as applicable.
      cardPayManager.fetchTransactionFee(this);
  }

  // Methods to override
  @Override
  public void onTransactionFeeFetched(String chargeAmount, String fee) {
      // Display the fee to the customer, then proceed to payment at your 
      // discretion using cardPayManager.chargeCard(card);
  }

  @Override
  public void onFetchFeeError(String errorMessage) {
      //Display error to user, or  proceed  with payment at your discretion
  }

}

Card Save Feature

For Card transactions, if you would like to implement the card saving feature, make your calling class implement the SavedCardListener, then pass this as an argument to the constructor of CardPaymentManager. You can also set the savedCardListener using CardPaymentManager.setSavedCardsListener(this).

  • To save a card, call CardPaymentManager.saveCard() after a card payment is successful (before starting another payment).
  • To fetch the user's saved cards, use CardPaymentManager.fetchSavedCards(boolean).
  • To delete a saved card, use CardPaymentManager.deleteSavedCard(cardHash).
Example 
public class PaymentActivity extends AppCompatActivity implements SavedCardsListener, CardPaymentCallback 
{  
  //...
  //...
  
  // To save a card, call `CardPaymentManager.saveCard()` after a card payment is successful (before starting another payment).
  
  /**
   * Fetch the user's saved cards. The overridden functions will be called as applicable.
   */
  void fetchUserSavedCards(){
      cardPayManager.fetchSavedCards();
  }
  
  /**
   * Fetch the user's saved cards. The overridden functions will be called as applicable.
   */
  void deleteSavedCard(SavedCard card){
      cardPayManager.deleteSavedCard(card.getCardHash());
  }

  // Methods to override
  @Override
  public void onSavedCardsLookupSuccessful(List<SavedCard> cards, String phoneNumber) {
      // Check that the list is not empty, show the user to select which they'd like to charge, then proceed to 
      // charge the saved card using cardPayManager.chargeSavedCard(savedCard)
  }

  @Override
  public void onSavedCardsLookupFailed(String message) {
      // Saved card lookup failed. 
  }

  @Override
  public void collectOtpForSaveCardCharge() {
      // Collect otp and pass to the payment manager using cardPayManager.submitOtp()
  }

  @Override
  public void onCardSaveSuccessful(String phoneNumber) {
      //card saved successfully
  }

  @Override
  public void onCardSaveFailed(String message) {
      //Unable to save card
  }

  @Override
  public void onDeleteSavedCardRequestSuccessful() {
      // Card deleted successfully
  }

  @Override
  public void onDeleteSavedCardRequestFailed(String message) {
      //Unable to delete card
  }

}