Flutter SDK
This page is a guide to installing and using MoneyHash's Flutter SDK. You will find here the prerequisites to using our integration, the necessary requirements, how to configure the SDK in your app, and finally, how you can use it.
Prerequisites
Below, you will find all you need to do before integrating to MoneyHash with Android SDK:
- Get Started with MoneyHash to access your own Organization.
- Create an Account within your Organization.
- Connect providers to your new Account.
- Set up your Payment Defaults.
- Get your API keys in the dashboard to be able to make API calls.
Requirements
The following are the requirements to be able to install Flutter SDK on Android or iOS:
Android
- Compatible with apps targeting Android 5.0 (API level 21) and above.
- Use Kotlin version 1.8.10 and above.
- Using an up-to-date Android Gradle Plugin.
- AndroidX (as of v11.0.0).
iOS
- Compatible with apps targeting iOS 11 or above.
Installation
To install and configure the SDK in your project, do these simple steps:
- Run the following command for both Android and iOS to install:
dart pub add moneyhash_payment
Android
Android requires a few extra steps of configuration:
- Enable
viewBinding
in your project.
buildFeatures {
viewBinding true
}
- Change the MainActivity to extend
FlutterFragmentActivity
instead ofFlutterActivity
inandroid/app/src/main/kotlin/.../MainActivity.kt
:
import io.flutter.embedding.android.FlutterFragmentActivity
class MainActivity: FlutterFragmentActivity()
Integrating
You can start the integration after configuring MoneyHash's Flutter SDK into your application. Below, you will find the essential steps to use this integration:
-
First, create an
intent
with the Payment intent endpoint. This step does not use MoneyHash's Flutter SDK and is standard for all MoneyHash's integrations, except for HPP. This endpoint requires authentication to be executed properly. You need to provide the Account API Key as a header and send the required data in the request body. Check the Create an Intent page for further explanation.
- Create a MoneyHash instance using the
MoneyHashSDKBuilder.build
method.
import 'package:moneyhash_payment/moneyhash_payment.dart';
MoneyHashSDK moneyhashSDK = MoneyHashSDKBuilder.build();
- Get intent details: Calling the
getIntentDetails
method with theintent_id
from theintent
created at Step 1, and theIntentType.payment
(Payment/Payout) as parameters, you are able to access your intent details. Thestate
returned can guide you through the actions and methods required to proceed and complete the payment or payout. The table below describes each action related to each possiblestate
value.
try{
var result = await moneyhashSDK.getIntentDetails(intentId, IntentType.payment);
} catch (e) {
// Handle the errors
}
state | Action |
---|---|
METHOD_SELECTION | Use moneyHash.getIntentMethods to get the different payment methods available for the intent. You can render them natively with your own styles and use moneyHash.proceedWithMethod to proceed with one of them after the user selection. |
INTENT_FORM | Use moneyHash.renderForm to start the SDK flow to let MoneyHash handle the flow for you and listen for the result by using IntentContract() to track the end of the process. |
INTENT_PROCESSED | Render your successful confirmation UI with the intent details. |
TRANSACTION_FAILED | Render your failure UI with the intent details. |
TRANSACTION_WAITING_USER_ACTION | Render your pending actions confirmation UI with the intent details and externalActionMessage if exists on Transaction . |
EXPIRED | Render your intent expired UI. |
CLOSED | Render your intent closed UI |
Render SDK embed forms and payment integrations
If the state
returned is INTENT_FORM
you must call the renderForm
method to let MoneyHash handle the payment/payout. You can use it directly to render the embed form for
payment/payout without handling the methods selection native UI.
try {
var result = await moneyhashSDK.renderForm(intentId, IntentType.payment);
} catch (e) {
// handle the error
}
- Get intent methods: Calling the
getIntentMethods
sending theintent_id
as the parameter, you have access to the available pay-in/pay-out methods, saved cards, and customer balances. For example, you could use this information to predefine a payment method. Or choose whichpaymentMethods
to display to give the customer the option to choose their preferred method.
try{
var result = await moneyhashSDK.getIntentMethods(intentId, IntentType.payment);
} catch (e) {
// Handle the errors
}
- Proceed with payment: Using the
proceedWithMethod
method, you can proceed with the payment process. You are required to inform theintentId
,intentType.payment
,selectedMethodId
,methodType.customerBalance
andmethodMetaData
to execute this method.
try {
var result = await moneyhashSDK.proceedWithMethod(
intentId,
IntentType.payment,
selectedMethodId,
MethodType.customerBalance, // method type that returned from the intent methods
MethodMetaData(// optional and can be null
cvv: "123", // required for customer saved cards that requires cvv
)
);
} catch (e) {
// handle the error
}
Other available Flutter SDK methods
In addition to the essential steps and methods previously described, the Flutter SDK provides other methods to customize the user experience. These additional methods are presented and described next.
- Reset selected method: You can use the
resetSelectedMethod
method for different situations:- Give the customer a button as an option to go back after they already selected a payment method.
- Offer a retry button so your customer can select a different payment method after a transaction has failed.
try {
var result = await moneyhashSDK.resetSelectedMethod(intentId, IntentType.payment);
} catch (e) {
// handle the error
}
- Delete card: Call the
deleteSavedCard
method to delete a customer's saved card from the system. You can use this option when listing the existing customer's saved cards.
try {
await moneyhashSDK.deleteSavedCard(cardTokenId, intentSecret); // No result expected from this method success or failure
} catch (e) {
// handle the error
}
Event Listeners
Android
To stay up to date with the events related to payments/payouts, you need to add PaymentActivity
/ PayoutActivity
to AndroidManifest.xml.
<activity android:name="com.moneyhash.sdk.android.payment.PaymentActivity"
android:theme="@style/Theme.AppCompat.Light.NoActionBar.FullScreen"/>
<activity android:name="com.moneyhash.sdk.android.payout.PayoutActivity"
android:theme="@style/Theme.AppCompat.Light.NoActionBar.FullScreen"/>
Responses
To help you proceed and organize your code, we provide all possible response types for the methods you can use on the Flutter SDK.
class CustomerBalance {
final double? balance;
final String? id;
final String? icon;
final bool? isSelected;
final MethodType? type;
}
class PaymentMethod {
final String? id;
final String? title;
final bool? isSelected;
final bool? confirmationRequired;
final List<String>? icons;
final MethodType? type;
}
class PayoutMethod {
final String? id;
final String? title;
final bool? isSelected;
final bool? confirmationRequired;
final List<String>? icons;
final MethodType? type;
}
class ExpressMethod {
final String? id;
final String? title;
final bool? isSelected;
final bool? confirmationRequired;
final List<String>? icons;
final MethodType? type;
}
class SavedCard {
final String? id;
final String? brand;
final String? last4;
final String? expiryMonth;
final String? expiryYear;
final String? country;
final String? logo;
final bool? requireCvv;
final CvvConfig? cvvConfig;
final MethodType? type;
}
class CvvConfig {
final int? digitsCount;
}
class IntentMethods {
final List<CustomerBalance>? customerBalances;
final List<PaymentMethod>? paymentMethods;
final List<ExpressMethod>? expressMethods;
final List<SavedCard>? savedCards;
final List<PayoutMethod>? payoutMethods;
}
enum MethodType {
expressMethod,
customerBalance,
savedCard,
paymentMethod,
payoutMethod,
}
class IntentDetails {
final String? selectedMethod;
final IntentData? intent;
final double? walletBalance;
final TransactionData? transaction;
final RedirectData? redirect;
final IntentState? state;
}
class TransactionData {
final String? billingData;
final double? amount;
final List<String>? externalActionMessage;
final String? amountCurrency;
final String? id;
final String? methodName;
final String? method;
final String? createdDate;
final String? status;
final String? customFields;
final String? providerTransactionFields;
final String? customFormAnswers;
}
class IntentData {
final AmountData? amount;
final String? secret;
final String? expirationDate;
final bool? isLive;
final String? id;
final IntentStatus? status;
}
class AmountData {
final String? value;
final double? formatted;
final String? currency;
final double? maxPayout;
}
class RedirectData {
final String? redirectUrl;
}
class IntentResult {
final IntentMethods? methods;
final IntentDetails? details;
}
enum IntentType {
payment,
payout
}
class MethodMetaData {
final String? cvv;
}
enum IntentStatus {
processed,
unProcessed,
timeExpired,
closed,
}
enum IntentState {
methodSelection,
intentForm,
intentProcessed,
transactionWaitingUserAction,
transactionFailed,
expired,
closed,
}
Questions and Issues
Please provide any feedback via a GitHub Issue.
Notifications
After integrating with MoneyHash through the Flutter SDK, it's recommended you learn how to configure and use Webhooks and Redirects to be able to receive notifications and automatically redirect your customer to where you want with ease.
Updated 8 days ago