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 of FlutterActivity in android/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.

POST

/api/v1.1/payments/intent/

Create a MoneyHash instance using theMoneyHashSDKBuilder.build method.

import 'package:moneyhash_payment/moneyhash_payment.dart';
MoneyHashSDK moneyhashSDK = MoneyHashSDKBuilder.build();

Get intent details: Calling the getIntentDetails method with the intent_id from the intent created at Step 1, and the IntentType.payment(Payment/Payout) as parameters, you are able to access your intent details. The state 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 possible state 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 the intent_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 which paymentMethods 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 the intentId, intentType.payment, selectedMethodId, methodType.customerBalance and methodMetaData 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.