Skip to content

Commit d69f156

Browse files
jeremiahAIjeremiahAI
committed
Update Readmes
1 parent bbc4b3f commit d69f156

File tree

2 files changed

+287
-51
lines changed

2 files changed

+287
-51
lines changed

‎CustomUiImplementation.md‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# Custom UI Implementation
2+
The Flutterwave SDK can be used with you custom UI where you handle the entire User Interface. This doc shows how to do so.
3+
4+
### 1. Create a `RaveNonUIManager` instance
5+
Set the public key, encryption key and other required parameters.
6+
7+
RaveNonUIManager raveNonUIManager =
8+
new RaveNonUIManager()
9+
.setAmount(amount)
10+
.setCurrency(currency)
11+
.setEmail(email)
12+
.setfName(fName)
13+
.setlName(lName)
14+
.setNarration(narration)
15+
.setPublicKey(publicKey)
16+
.setEncryptionKey(encryptionKey)
17+
.setTxRef(txRef)
18+
.setPhoneNumber(phoneNumber, boolean)
19+
.onStagingEnv(boolean)
20+
.setMeta(List<Meta>)
21+
.isPreAuth(boolean)
22+
.setSubAccounts(List<SubAccount>)
23+
.shouldDisplayFee(boolean)
24+
.showStagingLabel(boolean)
25+
.initialize();
26+
27+
<details>
28+
<summary>Function Definitions</summary>
29+
30+
31+
| function | parameter | type | required |
32+
| ------------- |:-------------:| -----:| -----:|
33+
| setAmount(amount) | This is the amount to be charged from card/account | `double` | Required
34+
| setCurrency(currency) | This is the specified currency to charge the card in | `String` | Required
35+
| setfName(fName) | This is the first name of the card holder or the customer | `String` | Required
36+
| setlName(lName) | This is the last name of the card holder or the customer | `String` | Required
37+
| setEmail(email) | This is the email address of the customer | `String` | Required
38+
| setNarration(narration) | This is a custom description added by the merchant. For `Bank Transfer` payments, this becomes the account name of the account to be paid into. See more details [here](https://developer.flutterwave.com/v2.0/reference#pay-with-bank-transfer-nigeria). | `String` | Not Required
39+
| setPublicKey(publicKey) | Merchant's public key. Get your merchant keys here for [ staging](https://flutterwavedevelopers.readme.io/blog/how-to-get-your-staging-keys-from-the-rave-sandbox-environment) and [live](https://flutterwavedevelopers.readme.io/blog/how-to-get-your-live-keys-from-the-rave-dashboard)| `String` | Required
40+
| setEncryptionKey(encryptionKey) | Merchant's encryption key. Get your merchant keys here for [ staging](https://flutterwavedevelopers.readme.io/blog/how-to-get-your-staging-keys-from-the-rave-sandbox-environment) and [live](https://flutterwavedevelopers.readme.io/blog/how-to-get-your-live-keys-from-the-rave-dashboard) | `String` | Required
41+
| setTxRef(txRef) | This is the unique reference, unique to the particular transaction being carried out. It is generated by the merchant for every transaction | `String` | Required
42+
| setPhoneNumber(phoneNumber) | This sets the customer's phone number. This functions is also overloaded to allow you specify whether the customer can edit their phone number as such: `setPhoneNumber(phoneNumber,false)`. When set to false, the user will not be able to change the number you set here.| `String`<br/><br/>Optional overloads:<br/>`String`, `boolean` | Not Required
43+
| onStagingEnv(boolean) | Set to `true` if you want your transactions to run in the staging environment otherwise set to `false`. Defaults to false | `boolean` | Not Required
44+
| setMeta(`List<Meta>`) | Pass in any other custom data you wish to pass. It takes in a `List` of `Meta` objects | List<Meta> | Not Required
45+
| setSubAccounts(`List<SubAccount>`) | Pass in a `List` of `SubAccount`,if you want to split transaction fee with other people. Subaccounts are your vendors' accounts that you want to settle per transaction. To initialize a `SubAccount` class, do `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](https://developer.flutterwave.com/docs/split-payment).| `List<SubAccount>`| Not Required
46+
| setIsPreAuth(boolean) | Set to `true` to preauthorise the transaction amount. [Learn more about preauthourization](https://developer.flutterwave.com/v2.0/reference#introduction-1). | `int` | Not Required
47+
| setPaymentPlan(payment_plan) | If you want to do recurrent payment, this is the payment plan ID to use for the recurring payment, you can see how to create payment plans [here](https://flutterwavedevelopers.readme.io/v2.0/reference#create-payment-plan) and [here](https://flutterwavedevelopers.readme.io/docs/recurring-billing). This is only available for card payments | `String` | Not Required
48+
| initialize() | Returns the prepared `RaveNonUiManager` that can be used with any of the payment managers for the different payment methods | N/A | Required
49+
</details>
50+
51+
### 2. Initiate a charge
52+
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).
53+
54+
CardPaymentManager cardPayManager = new CardPaymentManager(
55+
raveNonUIManager, CardPaymentCallback, SavedCardsListener);
56+
Card card = new Card(
57+
"5531886652142950")
58+
"12",
59+
"22",
60+
"123"
61+
); // Test MasterCard PIN
62+
63+
cardPayManager.chargeCard(card);
64+
65+
### 3. Implement callbacks
66+
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`
67+
<details>
68+
<summary>See Example</summary>
69+
70+
```java
71+
public class PaymentActivity extends AppCompatActivity implements CardPaymentCallback {
72+
73+
// Step 1 and Step 2 here...
74+
75+
// Methods to override for card payment
76+
@Override
77+
public void collectCardPin() {
78+
//collect PIN from User and pass to the CardPayManager object.
79+
cardPayManager.submitPin(pin);
80+
}
81+
82+
@Override
83+
public void collectOtp(String message) {
84+
//collect OTP from User and pass to the CardPayManager object.
85+
cardPayManager.submitOtp(otp);
86+
}
87+
88+
@Override
89+
public void collectAddress() {
90+
//collect Card Address details from User and pass to the CardPayManager object.
91+
cardPayManager.submitAddress(address);
92+
}
93+
94+
@Override
95+
public void showAuthenticationWebPage(String authenticationUrl) {
96+
//Show a Webview for transaction authentication and call the CardPayManager object when the webview authentication is done.
97+
// See the JavaDoc for this method for more details.
98+
99+
cardPayManager.onWebpageAuthenticationComplete();
100+
}
101+
102+
@Override
103+
public void onError(String errorMessage, @Nullable String flwRef) {
104+
// Error during transaction
105+
Toast.makeText(this, errorMessage, Toast.LENGTH_LONG).show();
106+
}
107+
108+
@Override
109+
public void onSuccessful(String flwRef) {
110+
// Transaction successful
111+
Toast.makeText(this, "Transaction Successful", Toast.LENGTH_LONG).show();
112+
}
113+
}
114+
115+
```
116+
117+
</details>
118+
119+
<details>
120+
<summary>See All Payment Managers and Callbacks</summary>
121+
122+
## Payment Methods and corresponding PaymentManager and Callback class names
123+
| Payment Method | Payment Manager Class | Payment Callback Class |
124+
| ------------- |:-------------:| -----:|
125+
| Account (Direct Debit) | `AccountPaymentManager` | `AccountPaymentCallback`
126+
| ACH | `AchPaymentManager` | `AchPaymentCallback`
127+
| Bank Transfer | `BankTransferPaymentManager` | `BankTransferPaymentCallback`
128+
| Barter | `BarterPaymentManager` | `BarterPaymentCallback`
129+
| Card | `CardPaymentManager` | `CardPaymentCallback`
130+
| Francophone Mobile Money | `FrancophoneMobileMoneyPaymentManager` | `FrancophoneMobileMoneyPaymentCallback`
131+
| Ghana Mobile Money | `GhMobileMoneyPaymentManager` | `GhMobileMoneyPaymentCallback`
132+
| MPesa | `MpesaPaymentManager` | `MpesaPaymentCallback`
133+
| Rwanda Mobile Money | `RwfMobileMoneyPaymentManager` | `RwfMobileMoneyPaymentCallback`
134+
| South Africa Bank Account | `SaBankAccountPaymentManager` | `SaBankAccountPaymentCallback`
135+
| Uganda Mobile Money | `UgandaMobileMoneyPaymentManager` | `UgandaMobileMoneyPaymentCallback`
136+
| UK Bank Payment | `UkBankPaymentManager` | `UkBankPaymentCallback`
137+
| USSD | `UssdPaymentManager` | `UssdPaymentCallback`
138+
| Zambia Mobile Money | `ZmMobileMoneyPaymentManager` | `ZmMobileMoneyPaymentCallback`
139+
</details>
140+
141+
> We worked on a module to simplify charge verification when using the No-UI approach. You can read about using it [here](ChargeVerificationUtils.md)
142+
143+
> 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.
144+
145+
> To see a more practical way of using the sdk, head to our sample app in the repository [here](https://github.com/Flutterwave/rave-android/tree/master/app)
146+
147+
## Configuring Proguard
148+
To configure Proguard, add the following lines to your proguard configuration file. These will keep files related to this sdk
149+
```
150+
keepclasseswithmembers public class com.flutterwave.raveandroid.** { *; }
151+
dontwarn com.flutterwave.raveandroid.card.CardFragment
152+
```
153+
154+
155+
## Extras
156+
### Fee checking
157+
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.
158+
159+
<details>
160+
<summary>Example</summary>
161+
162+
```java
163+
public class PaymentActivity extends AppCompatActivity
164+
implements FeeCheckListener // Implement if you want to be able to check fees beforehand
165+
// Don't forget to implement the payment callback(s) for the payment method(s) you want to use.
166+
{
167+
168+
//...
169+
//...
170+
void fetchFee(){
171+
// Call the fetch transaction fee function with `this` as an argument. The overridden callbacks will then be called as applicable.
172+
cardPayManager.fetchTransactionFee(this);
173+
}
174+
175+
// Methods to override
176+
@Override
177+
public void onTransactionFeeFetched(String chargeAmount, String fee) {
178+
// Display the fee to the customer then proceed to payment at your
179+
// discretion using cardPayManager.chargeCard(card);
180+
}
181+
182+
@Override
183+
public void onFetchFeeError(String errorMessage) {
184+
//Display error to user, or proceed with payment at your discretion
185+
}
186+
187+
}
188+
189+
```
190+
191+
</details>
192+
193+
### Card Save Feature
194+
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`.
195+
* To save a card, call `CardPaymentManager.saveCard()` after a card payment is successful (before starting another payment).
196+
* To fetch the user's saved cards, use `CardPaymentManager.fetchSavedCards(boolean)`.
197+
* To delete a saved card, use `CardPaymentManager.deleteSavedCard(cardHash)`.
198+
199+
200+
<details>
201+
<summary>Example</summary>
202+
203+
```java
204+
public class PaymentActivity extends AppCompatActivity implements SavedCardsListener, CardPaymentCallback
205+
{
206+
//...
207+
//...
208+
209+
// To save a card call `CardPaymentManager.saveCard()` after a card payment is successful (before starting another payment).
210+
211+
/**
212+
* Fetch the user's saved cards. The overridden functions will be called as applicable.
213+
*/
214+
void fetchUserSavedCards(){
215+
cardPayManager.fetchSavedCards();
216+
}
217+
218+
/**
219+
* Fetch the user's saved cards. The overridden functions will be called as applicable.
220+
*/
221+
void deleteSavedCard(SavedCard card){
222+
cardPayManager.deleteSavedCard(card.getCardHash());
223+
}
224+
225+
// Methods to override
226+
@Override
227+
public void onSavedCardsLookupSuccessful(List<SavedCard> cards, String phoneNumber) {
228+
// Check that the list is not empty, show the user to select which they'd like to charge, then proceed to
229+
// charge the saved card using cardPayManager.chargeSavedCard(savedCard)
230+
}
231+
232+
@Override
233+
public void onSavedCardsLookupFailed(String message) {
234+
// Saved card lookup failed.
235+
}
236+
237+
@Override
238+
public void collectOtpForSaveCardCharge() {
239+
// Collect otp and pass to the payment manager using cardPayManager.submitOtp()
240+
}
241+
242+
@Override
243+
public void onCardSaveSuccessful(String phoneNumber) {
244+
//card saved successful
245+
}
246+
247+
@Override
248+
public void onCardSaveFailed(String message) {
249+
//Unable to save card
250+
}
251+
252+
@Override
253+
public void onDeleteSavedCardRequestSuccessful() {
254+
// Card deleted successfully
255+
}
256+
257+
@Override
258+
public void onDeleteSavedCardRequestFailed(String message) {
259+
//Unable to delete card
260+
}
261+
262+
}
263+
264+
```
265+
266+
</details>

0 commit comments

Comments
 (0)