@jimrising/easymerchantsdk-react-native 2.1.1 → 2.1.3

package/README.md

@@ -1,28 +1,29 @@
-# EasyMerchantSdk React Native Implementation
+# EasyMerchant SDK React Native Integration
 
-This guide provides step-by-step instructions to integrate the EasyMerchantSdk into your React Native application for both Android and iOS platforms. The SDK supports identical parameters for both platforms, with differences only in the method calls for initiating payments and handling responses.
+This guide provides step-by-step instructions for integrating the EasyMerchant SDK into a React Native application for Android and iOS platforms. The SDK supports identical configuration parameters for both platforms, with slight differences in method calls for initiating payments and handling responses. This project includes a sample implementation (`App.js`) that demonstrates a fully configurable payment interface with support for card payments, ACH transfers, recurring payments, 3D Secure authentication, and customizable billing/additional information fields.
 
 ## Prerequisites
 
-- Node.js and npm installed
-- React Native development environment set up
-- Ruby 3.2.8 (for iOS setup)
-- Xcode (for iOS development)
-- Android Studio (for Android development)
+- **Node.js and npm**: Ensure Node.js (v16 or higher) and npm are installed.
+- **React Native Environment**: Set up a React Native development environment as per the [official documentation](https://reactnative.dev/docs/environment-setup).
+- **Ruby**: Version 3.2.8 or higher for iOS setup (required for CocoaPods).
+- **Xcode**: Version 14 or higher for iOS development.
+- **Android Studio**: For Android development, with Gradle configured.
+- **EasyMerchant SDK Credentials**: Obtain API keys and secret keys for `sandbox` and `staging` environments from your EasyMerchant account.
 
 ## Installation
 
 ### 1. Add the SDK to Your Project
 
-Add the EasyMerchantSdk to your project by including it in your `package.json` file under the `dependencies` section:
+Add the EasyMerchant SDK to your project by including it in your `package.json` under the `dependencies` section:
 
 ```json
 "dependencies": {
-  "@jimrising/easymerchantsdk-react-native": "^2.1.1"
+  "@jimrising/easymerchantsdk-react-native": "^2.1.3"
 }
 ```
 
-Alternatively, install it using the following command:
+Alternatively, install it using npm:
 
 ```bash
 npm install @jimrising/easymerchantsdk-react-native
@@ -31,7 +32,7 @@ npm install @jimrising/easymerchantsdk-react-native
 ### 2. Android Configuration
 
 1. Open the `android/build.gradle` file in your project.
-2. Add the following code to the `allprojects.repositories` section to ensure the SDK can access required dependencies:
+2. Add the following to the `allprojects.repositories` section to include the SDK's dependencies:
 
 ```gradle
 allprojects {
@@ -50,12 +51,13 @@ allprojects {
 }
 ```
 
-3. Sync your project with Gradle to apply the changes.
+3. Ensure `GITHUB_URL`, `GITHUB_USERNAME`, and `GITHUB_PASSWORD` are defined in your `gradle.properties` file or provided via your CI/CD system.
+4. Sync your project with Gradle to apply the changes.
 
 ### 3. iOS Configuration
 
 1. **Update AppDelegate.swift**  
-   Create or modify the `AppDelegate.swift` file in your iOS project to include the following code:
+   Modify or create the `ios/AppDelegate.swift` file to initialize the React Native bridge and set up the EasyMerchant SDK:
 
 ```swift
 import UIKit
@@ -90,7 +92,7 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
 
         let rootView = RCTRootView(
             bridge: validBridge,
-            moduleName: "EasyMerchantTestApp", // Replace with your app name
+            moduleName: "EasyMerchantTestApp", // Replace with your app's module name
             initialProperties: nil
         )
 
@@ -111,7 +113,7 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
 ```
 
 2. **Update Podfile**  
-   Open your `ios/Podfile` and add the following to include the EasyMerchantSdk pod:
+   In your `ios/Podfile`, add the EasyMerchant SDK pod:
 
 ```ruby
 require_relative '../node_modules/react-native/scripts/react_native_pods'
@@ -119,34 +121,34 @@ require_relative '../node_modules/@react-native-community/cli-platform-ios/nativ
 
 platform :ios, '16.0'
 
-pod 'easymerchantsdk', :path => '../node_modules/easymerchantsdk-react-native/ios'
+pod 'easymerchantsdk', :path => '../node_modules/@jimrising/easymerchantsdk-react-native/ios'
 ```
 
-3. Run `pod install` in the `ios` directory to install the dependencies:
+3. Install the pod dependencies by running:
 
 ```bash
 cd ios
-pod install
+pod install --repo-update
 ```
 
-## Usage in Your React Native App
+## Usage
 
-To integrate the EasyMerchantSdk into your React Native application, you can use the provided `App.js` as a reference. The parameters for Android and iOS are identical, but the method calls differ slightly.
+The sample `App.js` provides a complete implementation for integrating the EasyMerchant SDK, including a user interface for configuring payment settings and handling responses. Below is a guide to using the SDK in your React Native application.
 
-### 1. Import Necessary Modules
+### 1. Import Required Modules
 
-Ensure you import the required React Native components and the EasyMerchantSdk NativeModules:
+Ensure you import the necessary React Native components and the EasyMerchant SDK NativeModules:
 
 ```javascript
 import React, { useState, useEffect } from 'react';
-import { StyleSheet, Text, View, TextInput, Button, Alert, ScrollView, Platform, NativeModules, Switch, TouchableOpacity, NativeEventEmitter, KeyboardAvoidingView, Keyboard, TouchableWithoutFeedback, Modal } from 'react-native';
+import { StyleSheet, Text, View, TextInput, Switch, TouchableOpacity, NativeModules, NativeEventEmitter, Platform, Alert, ScrollView, KeyboardAvoidingView, Modal, TouchableWithoutFeedback } from 'react-native';
 
 const { RNEasymerchantsdk, EasyMerchantSdk } = NativeModules;
 ```
 
-### 2. Set Up Configuration
+### 2. Define Configuration
 
-Define the configuration object for the SDK, which is shared between Android and iOS. The provided `App.js` includes a comprehensive `externalConfig` object that you can customize:
+Use a configuration object to define payment settings. The `externalConfig` in `App.js` is a comprehensive example that supports both platforms:
 
 ```javascript
 const externalConfig = {
@@ -157,16 +159,16 @@ const externalConfig = {
   isSecureAuthentication: false,
   isBillingVisible: false,
   isAdditionalVisible: false,
-  emailEditable: true,
-  isEmail: true,
+  emailEditable: true, // Android-specific
+  isEmail: true, // iOS-specific
   billingInfo: {
     visibility: { billing: false, additional: false },
     billing: {
-      address: 'Address',
-      country: 'Country',
-      state: 'State',
-      city: 'City',
-      postal_code: '000000',
+      address: 'San Fran',
+      country: 'USA',
+      state: 'California',
+      city: 'Paris',
+      postal_code: '234234',
     },
     billingRequired: {
       address: true,
@@ -178,7 +180,7 @@ const externalConfig = {
     additional: {
       name: 'Test User',
       email_address: 'test@gmail.com',
-      phone_number: '2140871329',
+      phone_number: '0000000',
       description: 'Test',
     },
     additionalRequired: {
@@ -213,10 +215,10 @@ const externalConfig = {
   recurringData: {
     allowCycles: 2,
     intervals: ['daily', 'weekly', 'monthly'],
-    recurringStartType: Platform.OS === 'android' ? 'Custom' : 'custom',
+    recurringStartType:  'custom',
     recurringStartDate: new Date().toLocaleDateString('en-US', { month: '2-digit', day: '2-digit', year: 'numeric' }),
   },
-  configur: {
+  androidConfig: {
     currency: 'usd',
     saveCard: true,
     saveAccount: true,
@@ -224,7 +226,7 @@ const externalConfig = {
     showDonate: false,
     showTotal: true,
     showSubmitButton: true,
-    paymentMethod: ['card', 'ach'],
+    paymentMethods: ['card', 'ach'],
     name: '',
     fields: {
       visibility: { billing: false, additional: false },
@@ -263,17 +265,88 @@ const externalConfig = {
 };
 ```
 
-### 3. Handle Payments
+This configuration includes:
+- **Basic Info**: `amount`, `email`, `name`.
+- **Payment Options**: Toggles for recurring payments, authenticated ACH, 3D Secure, and visibility of billing/additional fields.
+- **Billing Info**: Configurable billing and additional fields with required flags.
+- **Theming**: Separate `themeConfiguration` (iOS) and `androidConfig.appearanceSettings` (Android) for UI customization.
+- **GrailPay Params**: Settings for bank search UI (e.g., role, timeout, branding).
+- **Recurring Data**: Options for recurring payment cycles and intervals.
+- **Android Config**: Android-specific settings, including payment methods and fields.
 
-The `handlePayment` function validates inputs and calls platform-specific billing functions. The parameters are identical for both platforms, but the method calls differ.
+### 3. Initialize Environment
 
-#### Android: `handleAndroidBilling`
+Configure the SDK environment (`sandbox` or `staging`) with API keys and secret keys:
+
+```javascript
+const [apiKeys, setApiKeys] = useState({
+  sandbox: {
+    apiKey: 'apiKey',
+    secretKey: 'secretKey',
+  },
+  staging: {
+    apiKey: 'apiKey',
+    secretKey: 'secretKey',
+  },
+});
+
+useEffect(() => {
+  const updateEnvironment = async () => {
+    const { apiKey, secretKey } = apiKeys[environment];
+    if (Platform.OS === 'ios') {
+      try {
+        await EasyMerchantSdk.setViewController();
+        await EasyMerchantSdk.configureEnvironment(environment, apiKey, secretKey);
+      } catch (err) {
+        Alert.alert('Error', `Failed to configure iOS environment: ${err.message}`);
+      }
+    }
+  };
+  updateEnvironment();
+}, [environment, apiKeys]);
+```
+
+**Note**: Replace the placeholder API keys with your actual credentials. Store them securely (e.g., in environment variables) rather than hardcoding.
+
+### 4. Handle Payments
+
+The `handlePayment` function validates inputs and delegates to platform-specific billing handlers. At least one payment method (`card` or `ach`) must be selected, and recurring payments require at least one interval.
+
+#### Main Payment Handler
+
+```javascript
+const handlePayment = async () => {
+  if (!amount || isNaN(parseFloat(amount)) || parseFloat(amount) <= 0) {
+    return Alert.alert('Error', 'Please enter a valid amount');
+  }
+  if (isRecurring && (!recurringData.intervals || recurringData.intervals.length === 0)) {
+    return Alert.alert('Error', 'Please select at least one interval for recurring payment');
+  }
+  if (!androidConfig.paymentMethods || androidConfig.paymentMethods.length === 0) {
+    return Alert.alert('Error', 'Please select at least one payment method');
+  }
+
+  setLoading(true);
+  const timeoutId = setTimeout(() => setLoading(false), 3000);
+  try {
+    if (Platform.OS === 'android') {
+      await handleAndroidBilling();
+    } else {
+      await handleIosBilling();
+    }
+  } finally {
+    clearTimeout(timeoutId);
+    setLoading(false);
+  }
+};
+```
+
+#### Android Billing
 
 ```javascript
 const handleAndroidBilling = async () => {
   const { apiKey, secretKey } = apiKeys[environment];
-  const selectedPaymentMethods = [...configur.paymentMethod];
-
+  const selectedPaymentMethods = [...androidConfig.paymentMethods];
   const config = {
     amount,
     apiKey,
@@ -282,27 +355,30 @@ const handleAndroidBilling = async () => {
       environment,
       amount,
       tokenOnly: false,
-      currency: configur.currency,
-      saveCard: configur.saveCard,
-      saveAccount: configur.saveAccount,
+      currency: androidConfig.currency,
+      saveCard: androidConfig.saveCard,
+      saveAccount: androidConfig.saveAccount,
       authenticatedACH: isAuthenticatedACH,
       secureAuthentication: isSecureAuthentication,
-      showReceipt: configur.showReceipt,
-      showDonate: configur.showDonate,
-      showTotal: configur.showTotal,
-      showSubmitButton: configur.showSubmitButton,
-      paymentMethod: selectedPaymentMethods,
+      showReceipt: androidConfig.showReceipt,
+      showDonate: androidConfig.showDonate,
+      showTotal: androidConfig.showTotal,
+      showSubmitButton: androidConfig.showSubmitButton,
+      paymentMethods: selectedPaymentMethods,
       emailEditable,
       email,
       name,
       fields: {
-        ...configur.fields,
-        visibility: {
-          billing: isBillingVisible,
-          additional: isAdditionalVisible,
-        },
+        ...androidConfig.fields,
+        visibility: { billing: isBillingVisible, additional: isAdditionalVisible },
+      },
+      metadata: {
+        metaKey: 'metaValue',
+        metaKLey1: 'metaValue1',
+        metaKLey2: 'metaValue2',
+        metaKLey3: 'metaValue3',
+        metaKLey4: 'metaValue4',
       },
-      metadata,
       ...(isRecurring && {
         recurring: {
           enableRecurring: true,
@@ -310,7 +386,7 @@ const handleAndroidBilling = async () => {
         },
       }),
       grailPayParams,
-      appearanceSettings: configur.appearanceSettings,
+      appearanceSettings: androidConfig.appearanceSettings,
     },
   };
 
@@ -323,32 +399,29 @@ const handleAndroidBilling = async () => {
     };
     setResult(JSON.stringify(parsedResponse, null, 2));
   } catch (error) {
-    setResult(`Error: ${error.message ?? JSON.stringify(error)}`);
-    Alert.alert('Payment Error', error.message ?? 'Unknown error');
-  } finally {
-    setLoading(false);
+    setResult(`Error: ${error.message || 'Unknown error'}`);
+    Alert.alert('Payment Error', error.message || 'An error occurred during payment');
   }
 };
 ```
 
-#### iOS: `handleIosBilling`
+#### iOS Billing
 
 ```javascript
 const handleIosBilling = async () => {
-  const selectedPaymentMethodsIOS = [...configur.paymentMethod].map(method => 
+  const selectedPaymentMethodsIOS = androidConfig.paymentMethods.map(method =>
     method === 'card' ? 'Card' : method === 'ach' ? 'Bank' : method
   );
-
   try {
     const result = await EasyMerchantSdk.billing(
       amount,
-      'usd', // Default currency
+      androidConfig.currency || 'usd',
       billingInfo,
       selectedPaymentMethodsIOS,
       themeConfiguration,
-      false, // tokenOnly
-      true, // saveCard
-      true, // saveAccount
+      false,
+      androidConfig.saveCard,
+      androidConfig.saveAccount,
       isAuthenticatedACH,
       grailPayParams,
       'Submit',
@@ -358,74 +431,71 @@ const handleIosBilling = async () => {
       isRecurring ? recurringData.recurringStartType : '',
       isRecurring ? recurringData.recurringStartDate : '',
       isSecureAuthentication,
-      true, // showReceipt
-      true, // showTotal
-      true, // showSubmitButton
+      androidConfig.showReceipt,
+      androidConfig.showTotal,
+      androidConfig.showSubmitButton,
       isEmail,
       email,
       name,
-      metadata
+      {
+        metaKey: 'metaValue',
+        metaKLey1: 'metaValue1',
+        metaKLey2: 'metaValue2',
+        metaKLey3: 'metaValue3',
+        metaKLey4: 'metaValue4',
+      }
     );
-
     const refToken = result?.additionalInfo?.threeDSecureStatus?.data?.ref_token;
     if (refToken) setReferenceToken(refToken);
     setResult(JSON.stringify(result, null, 2));
   } catch (error) {
-    setResult(`Billing Error: ${error.message || JSON.stringify(error)}`);
-  } finally {
-    setLoading(false);
+    setResult(`Billing Error: ${error.message || 'Unknown error'}`);
+    Alert.alert('Billing Error', error.message || 'An error occurred during billing');
   }
 };
 ```
 
-#### Main Payment Handler
+#### Helper Function for JSON Parsing
 
 ```javascript
-const handlePayment = async () => {
-  if (!amount || isNaN(parseFloat(amount)) || parseFloat(amount) <= 0) {
-    return Alert.alert('Error', 'Please enter a valid amount');
-  }
-
-  if (isRecurring && (!recurringData.intervals || recurringData.intervals.length === 0)) {
-    return Alert.alert('Error', 'Please select at least one interval for recurring payment');
-  }
-
-  setLoading(true);
-  const timeoutId = setTimeout(() => setLoading(false), 3000);
-
-  try {
-    if (Platform.OS === 'android') {
-      await handleAndroidBilling();
-    } else {
-      await handleIosBilling();
+const safeParseMaybeJSON = (value) => {
+  if (typeof value === 'string') {
+    try {
+      return JSON.parse(value);
+    } catch (e) {
+      console.warn('Failed to parse JSON string:', value);
+      return value;
     }
-  } finally {
-    clearTimeout(timeoutId);
-    setLoading(false);
   }
+  return value;
 };
 ```
 
-### 4. Event Listeners for Android
+### 5. Android Event Listeners
 
-Set up event listeners for payment success, status, and errors using `NativeEventEmitter` (Android only):
+For Android, set up event listeners to handle payment success, status, and errors:
 
 ```javascript
 useEffect(() => {
   if (Platform.OS !== 'android') return;
+  if (!RNEasymerchantsdk) {
+    console.warn('RNEasymerchantsdk native module is not available.');
+    return;
+  }
 
   const easyMerchantEvents = new NativeEventEmitter(RNEasymerchantsdk);
-
   const successSub = easyMerchantEvents.addListener('PaymentSuccess', (data) => {
-    const parsed = JSON.parse(data.response);
-    setResult(JSON.stringify(parsed, null, 2));
+    const parsed = JSON.parse(data.response || '{}');
+    setResult(JSON.stringify({
+      ...parsed,
+      billingInfo: safeParseMaybeJSON(parsed.billingInfo),
+      additional_info: safeParseMaybeJSON(parsed.additional_info),
+    }, null, 2));
   });
-
   const statusSub = easyMerchantEvents.addListener('PaymentStatus', (data) => {
-    const parsed = JSON.parse(data.statusResponse);
+    const parsed = JSON.parse(data.statusResponse || '{}');
     setResult(JSON.stringify(parsed, null, 2));
   });
-
   const statusErrorSub = easyMerchantEvents.addListener('PaymentStatusError', (data) => {
     setResult(`Status Error: ${JSON.stringify(data.error, null, 2)}`);
   });
@@ -438,24 +508,20 @@ useEffect(() => {
 }, []);
 ```
 
-### 5. UI Components
-
-The provided `App.js` includes custom components like `Dropdown` and `FilledButton` for a user-friendly interface. Customize the styles in the `StyleSheet` to match your app's design.
-
 ## Notes
 
-- **Billing Info**: You can send `null` for `billingInfo` if it is not available.
-- **Environment Configuration**: The SDK supports `sandbox` and `staging` environments. Ensure you configure the correct API keys for each environment.
-- **Payment Methods**: The SDK supports `card` and `ach` payment methods (mapped to `Card` and `Bank` on iOS). Toggle them in the UI as needed.
-- **Recurring Payments**: Ensure at least one interval (`daily`, `weekly`, `monthly`) is selected when enabling recurring payments.
-- **Theming**: Customize the appearance using `themeConfiguration` for iOS or `configur.appearanceSettings` for Android to match your app's branding. The parameters are identical for both platforms.
-- **Method Differences**:
-    - **Android**: Use `RNEasymerchantsdk.makePayment(config)` with a JSON configuration object.
-    - **iOS**: Use `EasyMerchantSdk.billing(...)` with parameters passed directly.
-    - iOS supports an additional `paymentReference` method for checking payment status using a reference token.
+- **Billing Info**: Set `billingInfo` to `null` if not needed. Required fields are configurable via `billingRequired` and `additionalRequired`.
+- **Payment Methods**: Supported methods are `card` and `ach` (mapped to `Card` and `Bank` on iOS). Ensure at least one is selected in `androidConfig.paymentMethods`.
+- **Recurring Payments**: Requires at least one interval (`daily`, `weekly`, `monthly`) when enabled.
+- **Security**: Store API keys and secret keys securely (e.g., in environment variables or secure storage) rather than hardcoding.
+- **Platform Differences**:
+  - **Android**: Uses `RNEasymerchantsdk.makePayment(config)` with a JSON config object. Payment methods are lowercase (`['card', 'ach']`).
+  - **iOS**: Uses `EasyMerchantSdk.billing(...)` with parameters passed directly. Payment methods are capitalized (`['Card', 'Bank']`).
+  - iOS supports `paymentReference` for status checks; Android uses `checkPaymentStatus`.
 
 ## Troubleshooting
 
-- **iOS Bridge Initialization**: If you see "Failed to retrieve EasyMerchantSdkPlugin instance" in the console, ensure the `easymerchantsdk` pod is correctly installed and linked.
-- **Android Payment Issues**: Verify that `paymentMethod` is correctly formatted (`['card', 'ach']`) and that API keys are valid. Ensure `GITHUB_URL`, `GITHUB_USERNAME`, and `GITHUB_PASSWORD` are correctly set in your Gradle properties.
+- **iOS Bridge Initialization**: If you see "Failed to retrieve EasyMerchantSdkPlugin instance" in the console, verify that the `easymerchantsdk` pod is installed and linked correctly. Run `pod install --repo-update` and check `AppDelegate.swift`.
+- **Android Payment Issues**: Ensure `paymentMethods` is formatted as `['card', 'ach']` and that API keys are valid. Verify `GITHUB_URL`, `GITHUB_USERNAME`, and `GITHUB_PASSWORD` in `gradle.properties`.
 - **Pod Installation**: If `pod install` fails, ensure Ruby 3.2.8 is installed and run `pod install --repo-update`.
+- **Payment Failures**: Check console logs for detailed errors. Validate that `amount` is a positive number, payment methods are selected, and API keys are correct.

package/android/.gradle/buildOutputCleanup/cache.properties

@@ -1,2 +1,2 @@
-#Fri Aug 08 13:51:00 IST 2025
-gradle.version=8.9
+#Tue Aug 19 19:48:34 IST 2025
+gradle.version=8.10

package/android/build/intermediates/incremental/debug/packageDebugResources/compile-file-map.properties

@@ -1 +1 @@
-#Fri Aug 15 11:27:45 IST 2025
+#Wed Aug 20 09:54:15 IST 2025

package/android/src/main/java/com/reactlibrary/RNEasymerchantsdkModule.java

@@ -118,12 +118,26 @@ public class RNEasymerchantsdkModule extends ReactContextBaseJavaModule {
                 }
 
 
-                JSONArray paymentMethods = new JSONArray();
-                ReadableArray methods = jsonConfigMap.getArray("paymentMethod");
-                for (int i = 0; i < methods.size(); i++) {
-                    paymentMethods.put(methods.getString(i));
+                // Payment Methods
+                if (jsonConfigMap.hasKey("paymentMethods") && !jsonConfigMap.isNull("paymentMethods")) {
+                    ReadableArray methods = jsonConfigMap.getArray("paymentMethods");
+                    JSONArray paymentMethods = new JSONArray();
+
+                    for (int i = 0; i < methods.size(); i++) {
+                        if (methods.getType(i) == ReadableType.String) {
+                            // Case: simple array of strings
+                            paymentMethods.put(methods.getString(i));
+                        } else if (methods.getType(i) == ReadableType.Map) {
+                            // Case: array of objects
+                            ReadableMap item = methods.getMap(i);
+                            JSONObject obj = new JSONObject(item.toHashMap());
+                            paymentMethods.put(obj);
+                        }
+                    }
+
+                    jsonConfig.put("paymentMethods", paymentMethods);
                 }
-                jsonConfig.put("paymentMethod", paymentMethods);
+
 
                 // Recurring (flattened to match SDK)
                 if (jsonConfigMap.hasKey("recurring")) {

package/ios/easymerchantsdk.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name             = 'easymerchantsdk'
-  s.version          = '2.1.1'
+  s.version          = '2.1.3'
   s.summary          = 'A React Native SDK for Easy Merchant.'
   s.description      = <<-DESC
     A React Native SDK to enable Easy Merchant functionality in mobile applications.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jimrising/easymerchantsdk-react-native",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "",
   "main": "index.js",
   "scripts": {