React Native SDK

This page is a guide to installing and using MoneyHash's Android 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:

  1. Get Started with MoneyHash to get access to your own Organization.
  2. Create an Account within your Organization.
  3. Connect providers to your new Account.
  4. Set up your Payment Defaults.
  5. 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 React Native SDK, for Android or iOS:

Android

  • Compatible with apps targeting Android 5.0 (API level 21) and above
  • Use Kotlin version 1.6.10 and above: example
  • 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:

  1. Run the following command for both Android and iOS to install:
npm install @moneyhash/reactnative-sdk

Android

Android requires an extra step of configuration:

  • Enable viewBinding in your project.
 buildFeatures {
   viewBinding true
 }

Integrating

You can start the integration after configuring MoneyHash's React Native SDK into your application. Below, you will find the essential steps to use this integration:

  1. First, create an intent with the Payment intent endpoint. This step does not use MoneyHash's React Native 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/
  1. Create a MoneyHash instance using theMoneyHashSDKBuilder.build method.
import { MoneyHashSDKBuilder } from '@moneyhash/reactnative-sdk';
const moneyHash = MoneyHashSDKBuilder.build();
  1. 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 can 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.
  React.useEffect(() => {
  moneyHash
    .getIntentDetails('Intent id is here', IntentType.Payment)
    .then(setResult);
}, []);
stateAction
METHOD_SELECTIONUse 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_FORMUse 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_PROCESSEDRender your successful confirmation UI with the intent details.
TRANSACTION_FAILEDRender your failure UI with the intent details.
TRANSACTION_WAITING_USER_ACTIONRender your pending actions confirmation UI with the intent details and externalActionMessage if exists on Transaction.
EXPIREDRender your intent expired UI.
CLOSEDRender 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.

  React.useEffect(() => {
  moneyHash
    .renderForm('intent id is here', IntentType.Payment)
    .then(setResult);
}, []);

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 also use it directly to render the embed form for payment/payout without handling the methods selection native UI.

  React.useEffect(() => {
          moneyHash
            .renderForm('intent id is here', IntentType.Payment)
            .then(setResult);
        }, []);
        
  1. 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.
  React.useEffect(() => {
  moneyHash
    .getIntentMethods('Intent id is here', IntentType.Payment)
    .then(setResult);
}, []);
  1. Proceed with payment: Using the proceedWithMethod method, you are able to proceed with the payment process. You are required to inform the intentId, intentType.Payment, selected Method id and methodType.PaymentMethod to execute this method.
  React.useEffect(() => {
  moneyHash
    .proceedWithMethod(
      'Intent id is here',
      IntentType.Payment,
      'Selected Method id is here',
      MethodType.PaymentMethod,
      new MethodMetaData('CVV can be here') // Optional and will be considered only in case of saved card
    )
    .then(setResult);
}, []);

Other available React Native SDK methods

In addition to the essential steps and methods previously described, the React Native 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.
  React.useEffect(() => {
  moneyHash
    .resetSelectedMethod('Intent id is here', IntentType.Payment)
    .then(setResult);
}, []);
  • 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.
  React.useEffect(() => {
  moneyHash
    .deleteSavedCard('card token id', 'intent secret')
    .then(setResult);
}, []);

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 React Native SDK.

enum IntentType {
  Payment = 'payment',
  Payout = 'payout'
}

enum IntentStatus {
  Processed = 'PROCESSED',
    UnProcessed = 'UNPROCESSED',
    TimeExpired = 'TIME_EXPIRED',
    Closed = 'CLOSED',
}

enum IntentState {
  MethodSelection = 'METHOD_SELECTION',
    IntentForm = 'INTENT_FORM',
    IntentProcessed = 'INTENT_PROCESSED',
    TransactionWaitingUserAction = 'TRANSACTION_WAITING_USER_ACTION',
    TransactionFailed = 'TRANSACTION_FAILED',
    Expired = 'EXPIRED',
    Closed = 'CLOSED',
}

class IntentDetails {
  selectedMethod?: string;
  intent?: IntentData;
  walletBalance?: number;
  transaction?: TransactionData;
  redirect?: RedirectData;
  state?: IntentState;
}

class TransactionData {
  billingData?: string;
  amount?: number;
  externalActionMessage?: string[];
  amountCurrency?: string;
  id?: string;
  methodName?: string;
  method?: string;
  createdDate?: string;
  status?: string;
  customFields?: string;
  providerTransactionFields?: string;
  customFormAnswers?: string;
}

class IntentData {
  amount?: AmountData;
  secret?: string;
  expirationDate?: string;
  isLive?: boolean;
  id?: string;
  status?: IntentStatus;
}

class AmountData {
  value?: string;
  formatted?: number;
  currency?: string;
  maxPayout?: number;
}

class RedirectData {
  redirectUrl?: string;
}

class CustomerBalance {
  balance?: number;
  id?: string;
  icon?: string;
  isSelected?: boolean;
  type?: MethodType;
}

class PaymentMethod {
  id?: string;
  title?: string;
  isSelected?: boolean;
  confirmationRequired?: boolean;
  icons?: string[];
  type?: MethodType;
}

class PayoutMethod {
  id?: string;
  title?: string;
  isSelected?: boolean;
  confirmationRequired?: boolean;
  icons?: string[];
  type?: MethodType;
}

class ExpressMethod {
  id?: string;
  title?: string;
  isSelected?: boolean;
  confirmationRequired?: boolean;
  icons?: string[];
  type?: MethodType;
}

class SavedCard {
  id?: string;
  brand?: string;
  last4?: string;
  expiryMonth?: string;
  expiryYear?: string;
  country?: string;
  logo?: string;
  requireCvv?: boolean;
  cvvConfig?: CvvConfig;
  type?: MethodType;
}

class CvvConfig {
  digitsCount?: number;
}

class IntentMethods {
  customerBalances?: CustomerBalance[];
  paymentMethods?: PaymentMethod[];
  expressMethods?: ExpressMethod[];
  savedCards?: SavedCard[];
  payoutMethods?: PayoutMethod[];
}

class IntentResult {
  methods?: IntentMethods | null;
  details?: IntentDetails | null;
}

class MethodMetaData {
  cvv?: string;
}

enum MethodType {
  ExpressMethod = 'expressMethod',
    CustomerBalance = 'customerBalance',
    SavedCard = 'savedCard',
    PaymentMethod = 'paymentMethod',
    PayoutMethod = 'payoutMethod',
}

Notifications

After integrating with MoneyHash through the React Native 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.