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:
- Get Started with MoneyHash to get access to 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 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:
- 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:
-
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.
- Create a MoneyHash instance using the
MoneyHashSDKBuilder.build
method.
import { MoneyHashSDKBuilder } from '@moneyhash/reactnative-sdk';
const moneyHash = 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 can 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.
React.useEffect(() => {
moneyHash
.getIntentDetails('Intent id is here', IntentType.Payment)
.then(setResult);
}, []);
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 isINTENT_FORM
you must call therenderForm
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);
}, []);
- 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.
React.useEffect(() => {
moneyHash
.getIntentMethods('Intent id is here', IntentType.Payment)
.then(setResult);
}, []);
- Proceed with payment: Using the
proceedWithMethod
method, you are able to proceed with the payment process. You are required to inform theintentId
,intentType.Payment
,selected Method id
andmethodType.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.
Updated 5 months ago