@moneyhash/reactnative-sdk
v2.2.1
Published
React Native SDK for MoneyHash
Downloads
172
Readme
How to Use MoneyHash V2 React Native
Welcome to the MoneyHash SDK documentation for React Native! This guide provides an overview of the core functionalities of the MoneyHash SDK, including intent states, API methods, and models.
Intent States and Corresponding Actions
Here’s a summary of the different intent states defined in the React Native SDK and the actions associated with them:
| State | Action |
| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| MethodSelection | Handle this state by rendering the payment methods provided in methods
. After user selection, proceed with the selected method by calling moneyHashSDK.proceedWithMethod
. |
| FormFields | Handle this state by rendering form fields from billingFields
, shippingFields
, and tokenizeCardInfo
. Submit the completed data using moneyHashSDK.submitForm
. |
| UrlToRender | Use the moneyHashSDK.renderForm
to display the embed based on the URL provided. |
| SavedCardCVV | Render a CVV input field using cvvField
. Optionally, display card information from cardTokenData
. Submit the CVV using moneyHashSDK.submitCardCVV
. |
| IntentForm | Display the MoneyHash embed form using moneyHashSDK.renderForm
. |
| IntentProcessed | Render a success confirmation UI indicating the payment or payout completion with provided intent details. |
| TransactionWaitingUserAction | Show a UI element indicating the transaction awaits user action. If available, show any external action message required from Transaction
. |
| TransactionFailed | Display a UI element indicating transaction failure. If recommendedMethods
are provided, show these as alternative options for the user to retry the payment or payout. |
| Expired | Show a message indicating that the intent has expired. |
| Closed | Show a message indicating that the intent has been closed and no further actions can be taken. |
How to Handle Method Selection
Handling method selection is a crucial part of integrating the MoneyHash SDK. This process involves rendering available payment methods and managing the user's choice. Here’s how you can handle method selection effectively:
Steps to Handle Method Selection
Display Payment Methods:
- When the SDK state is
MethodSelection
, extract themethods
object which contains the available payment options for the intent. - Use your UI components to render these payment methods in a list or grid format, allowing the user to choose one.
- When the SDK state is
Capture User Selection:
- Implement an interactive element for each payment method. When a user selects a method, capture this selection and prepare to proceed with that method.
Proceed with the Selected Method:
- Use the
moneyHashSDK.proceedWithMethod
API call to initiate the payment process with the selected method. - Pass the necessary parameters, such as
intentId
,intentType
,selectedMethodId
, andmethodType
to this function. Optionally, include anymethodMetaData
if required by the payment process.
- Use the
Example Implementation
Here’s an example of how you might implement this in your React Native application:
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((result) => console.log(result))
.catch((error) => console.log(error));
Handling the FormFields
State
When handling the FormFields
state in MoneyHash, you will deal with two primary scenarios: managing billing or shipping data and handling card tokenization. These scenarios are broken down into steps for clarity.
Handling Billing or Shipping Data
Rendering Input Fields:
- Use
InputField
data to render form fields. Each field type corresponds to an attribute like name, address, etc., and comes with specific properties to guide the rendering.
- Use
Collecting User Input:
- Capture input from these fields in the form of a map where the key is the field name and the value is the user input.
Example of handling billing data:
const billingData = {
firstName: 'John',
lastName: 'Doe',
email: '[email protected]',
};
Handling Card Tokenization
Card tokenization securely captures sensitive card information and converts it into a token that can be safely stored and transmitted. Below is an example approach for handling card tokenization in React Native.
Example Implementation
import React from 'react';
import { View, Text, StyleSheet } from 'react-native';
import {
SecureCardForm,
SecureTextField,
useSecureCardForm
} from 'moneyhash-react-native-sdk';
export default function App() {
const { cardFormRef, collect, isValid, onFormValidityChange } = useSecureCardForm();
return (
<View style={styles.container}>
<SecureCardForm ref={cardFormRef} onFormValidityChange={onFormValidityChange}>
<SecureTextField
name="cardHolderName"
style={({ isFocused, isError }) => [
styles.input,
isFocused && styles.inputFocused,
isError && styles.inputError,
]}
placeholder="John Doe"
/>
<SecureTextField
name="cardNumber"
style={({ isFocused, isError }) => [
styles.input,
isFocused && styles.inputFocused,
isError && styles.inputError,
]}
placeholder="#### #### #### ####"
onCardBrandChange={(cardInfo) => {
console.log('cardBrand', cardInfo);
}}
/>
<View style={styles.row}>
<SecureTextField
name="expiryMonth"
style={({ isFocused, isError }) => [
styles.input,
isFocused && styles.inputFocused,
isError && styles.inputError,
{ flex: 1 },
]}
placeholder="MM"
/>
<SecureTextField
name="expiryYear"
style={({ isFocused, isError }) => [
styles.input,
isFocused && styles.inputFocused,
isError && styles.inputError,
{ flex: 1 },
]}
placeholder="YY"
/>
<SecureTextField
name="cvv"
style={({ isFocused, isError }) => [
styles.input,
isFocused && styles.inputFocused,
isError && styles.inputError,
{ flex: 2 },
]}
placeholder="***"
/>
</View>
</SecureCardForm>
<Button
title="Submit"
onPress={async () => {
const vaultData = await collect({
intentId: 'IntentID',
accessToken:
'Access Tocken',
shouldSaveCard: true // or false,
});
console.log('vaultData', vaultData);
const intentDetails = await moneyHashSDK.submitForm(
'IntentID',
'METHOD_ID',
{}, // Billing Data Record
{}, // Shipping Data Record
vaultData,
);
console.log('intentDetails', intentDetails);
}}
/>
</View>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
padding: 16,
},
input: {
borderWidth: 1,
borderColor: '#ccc',
padding: 8,
marginVertical: 4,
},
inputFocused: {
borderColor: '#007BFF',
},
inputError: {
borderColor: '#FF0000',
},
row: {
flexDirection: 'row',
justifyContent: 'space-between',
},
});
SecuredTextField Events
You can listen to different text field event like when the text field
- Changed
onChange
- Focused
onFocus
- Blured
onBlur
- Error Changed
onErrorChange
- Card Brand Change (Available on cardNumber field only)
onCardBrandChange
Note: MoneyHash considers card number valid based on the length only. Card number with length from 13 to 19 are considered valid.
<SecureTextField
name="cardNumber"
style={({ isFocused, isError }) => [
styles.input,
isFocused && styles.inputFocused,
isError && styles.inputError,
]}
placeholder="#### #### #### ####"
onChange={({ isValid, length, errorMessage }) => {
console.log('Change', { isValid, length, errorMessage });
}}
onFocus={() => {
console.log('Focus');
}}
onBlur={() => {
console.log('Blur');
}}
onErrorChange={({ isValid, errorMessage }) => {
console.log({ isValid, errorMessage });
}}
onCardBrandChange={(cardInfo) => { // available on CardNumber Only
console.log('cardBrand', cardInfo);
}}
/>
SecuredTextField Methods
You can programmatically focus, blur, clear SecureTextField
using ref to access internal methods
import {
SecureTextField,
type SecureTextFieldRef,
} from '@moneyhash/reactnative-sdk';
const cardNumberRef = useRef<SecureTextFieldRef>(null);
<SecureTextField
ref={cardNumberRef}
name="cardNumber"
style={({ isFocused, isError }) => [
styles.input,
isFocused && styles.inputFocused,
isError && styles.inputError,
]}
placeholder="#### #### #### ####"
onCardBrandChange={(cardInfo) => {
console.log('cardBrand', cardInfo);
}}
/>;
Then you will have access to
cardNumberRef.current?.focus();
cardNumberRef.current?.blur();
cardNumberRef.current?.clear();
Collecting the Card Data
Once the card form is rendered and filled out by the user, you can collect and tokenize the card data.
const vaultData = await collect({
intentId: 'IntentID',
accessToken: 'Access Tocken',
shouldSaveCard: true, // or false,
});
console.log('vaultData', vaultData);
Updating the Fees
In some scenarios, you may need to update the fees associated with a particular intent. Here’s how you can do it using the MoneyHash SDK in React Native:
Example Implementation
const feeItems: FeeItem[] = [
new FeeItem(
new Map<Language, string>([
[Language.ENGLISH, 'Service Fee'],
[Language.ARABIC, 'رسوم الخدمة'],
]),
'2'
),
new FeeItem(
new Map<Language, string>([
[Language.ENGLISH, 'Processing Fee'],
[Language.ARABIC, 'رسوم المعالجة'],
]),
'5'
),
new FeeItem(
new Map<Language, string>([
[Language.ENGLISH, 'Delivery Fee'],
[Language.ARABIC, 'رسوم التوصيل'],
]),
'6'
),
];
try {
const feesData = await moneyHashSDK.updateFees('ZpmnoP9', feeItems);
console.log('Fees updated successfully:', feesData);
} catch (error) {
console.error('Error updating fees:', error);
}
This example demonstrates how to update multiple fees associated with an intent by specifying the fee names and
amounts in different languages.
Updating the Discount
You can also update the discount associated with an intent using the MoneyHash SDK. Here’s an example of how to do that:
Example Implementation
const discountItem = new DiscountItem(
new Map<Language, string>([
[Language.ENGLISH, 'Service Fee'],
[Language.ARABIC, 'رسوم الخدمة'],
]),
DiscountType.AMOUNT,
'2'
);
try {
const discountData = await moneyHashSDK.updateDiscount(
'ZpmnoP9',
discountItem
);
console.log('Discount updated successfully:', discountData);
} catch (error) {
console.error('Error updating discount:', error);
}
This example shows how to update a discount by specifying the discount name in different languages, the type (amount or percentage), and the value.
Additional Requirements for Android
To use the MoneyHash SDK on Android, you must include the following activities in your AndroidManifest.xml file:
<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"/>
To ensure these activities are displayed in full-screen mode, you can define a custom style in your styles.xml file, as shown below:
<style name="Theme.AppCompat.Light.NoActionBar.FullScreen" parent="@style/Theme.AppCompat.Light.NoActionBar">
<item name="android:windowNoTitle">true</item>
<item name="android:windowActionBar">false</item>
<item name="android:windowFullscreen">true</item>
<item name="android:windowContentOverlay">@null</item>
</style>
Overview of MoneyHash APIs
For a detailed guide to all available APIs in the MoneyHash SDK for React Native, including parameters, return types, and usage examples, refer to the API Documentation.
Overview of MoneyHash Models
The MoneyHash SDK for React Native features various models to represent data structures like intents, payment methods, transactions, and card information. For comprehensive details on these models, including their properties and usage within the SDK, see the Model Documentation.
Questions and Issues
Please provide any feedback via a GitHub Issue.