@jimrising/easymerchantsdk-react-native 2.1.5 → 2.1.7

package/README.md

@@ -1,11 +1,12 @@
 # EasyMerchant SDK React Native Integration
 
-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.
+This guide provides step-by-step instructions for integrating the EasyMerchant SDK into a React Native application for both Android and iOS platforms. The SDK supports a unified configuration structure with minor platform-specific differences in method calls for initiating payments and handling responses. The provided `App.js` demonstrates a fully configurable payment interface supporting card payments, ACH transfers, recurring payments, 3D Secure authentication, and customizable billing/additional information fields with a user-friendly UI.
+
 
 ## Prerequisites
 
-- **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).
+- **Node.js and npm**: Version 16 or higher.
+- **React Native Environment**: Set up as per the [official React Native 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.
@@ -15,15 +16,15 @@ This guide provides step-by-step instructions for integrating the EasyMerchant S
 
 ### 1. Add the SDK to Your Project
 
-Add the EasyMerchant SDK to your project by including it in your `package.json` under the `dependencies` section:
+Add the EasyMerchant SDK to your `package.json` under `dependencies`:
 
 ```json
 "dependencies": {
-  "@jimrising/easymerchantsdk-react-native": "^2.1.5"
+  "@jimrising/easymerchantsdk-react-native": "^2.1.7"
 }
 ```
 
-Alternatively, install it using npm:
+Or install it via npm:
 
 ```bash
 npm install @jimrising/easymerchantsdk-react-native
@@ -31,8 +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 to the `allprojects.repositories` section to include the SDK's dependencies:
+1. Open `android/build.gradle` and add the following to the `allprojects.repositories` section:
 
 ```gradle
 allprojects {
@@ -41,7 +41,7 @@ allprojects {
         mavenCentral()
         maven { url 'https://jitpack.io' }
         maven {
-            url = uri(properties.getProperty('GITHUB_URL'))
+            url = uri("https://maven.pkg.github.com/jimrising/easymerchantsdk-react-native")
             credentials {
                 username = properties.getProperty('GITHUB_USERNAME')
                 password = properties.getProperty('GITHUB_PASSWORD')
@@ -51,13 +51,20 @@ allprojects {
 }
 ```
 
-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.
+2. Define `GITHUB_USERNAME` and `GITHUB_PASSWORD` in `android/gradle.properties` or your CI/CD system. For example:
+
+```properties
+GITHUB_USERNAME=your-github-username
+GITHUB_PASSWORD=your-github-token
+```
+
+3. Sync your project with Gradle to apply changes.
 
 ### 3. iOS Configuration
 
-1. **Update AppDelegate.swift**  
-   Modify or create the `ios/AppDelegate.swift` file to initialize the React Native bridge and set up the EasyMerchant SDK:
+1. **Update AppDelegate.swift**
+
+Modify `ios/AppDelegate.swift` to initialize the React Native bridge and set up the EasyMerchant SDK:
 
 ```swift
 import UIKit
@@ -102,7 +109,7 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
         self.window?.rootViewController = rootViewController
         self.window?.makeKeyAndVisible()
 
-        if let easyMerchantSdkPlugin = bridge?.module(for: EasyMerchantSdkPlugin.self) as? EasyMerchantSdkPlugin {
+        if let easyMerchantSdkPlugin = validBridge.module(for: EasyMerchantSdkPlugin.self) as? EasyMerchantSdkPlugin {
             easyMerchantSdkPlugin.setViewController(rootViewController)
         } else {
             print("Failed to retrieve EasyMerchantSdkPlugin instance from React Native bridge.")
@@ -112,19 +119,20 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
 }
 ```
 
-2. **Update Podfile**  
-   In your `ios/Podfile`, add the EasyMerchant SDK pod:
+2. **Update Podfile**
 
-```ruby
-require_relative '../node_modules/react-native/scripts/react_native_pods'
-require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'
+In `ios/Podfile`, add the EasyMerchant SDK pod:
 
+```ruby
 platform :ios, '16.0'
 
 pod 'easymerchantsdk', :path => '../node_modules/@jimrising/easymerchantsdk-react-native/ios'
+
+require_relative '../node_modules/react-native/scripts/react_native_pods'
+require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'
 ```
 
-3. Install the pod dependencies by running:
+3. Install pod dependencies:
 
 ```bash
 cd ios
@@ -133,172 +141,131 @@ pod install --repo-update
 
 ## Usage
 
-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.
+The provided `App.js` is a complete implementation showcasing the EasyMerchant SDK's capabilities with a configurable UI. Below is a guide to integrating and using the SDK in your React Native application.
 
 ### 1. Import Required Modules
 
-Ensure you import the necessary React Native components and the EasyMerchant SDK NativeModules:
+Import necessary React Native components and the EasyMerchant SDK NativeModules:
 
 ```javascript
 import React, { useState, useEffect } from 'react';
-import { StyleSheet, Text, View, TextInput, Switch, TouchableOpacity, NativeModules, NativeEventEmitter, Platform, Alert, ScrollView, KeyboardAvoidingView, Modal, TouchableWithoutFeedback } 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. Define Configuration
 
-Use a configuration object to define payment settings. The `externalConfig` in `App.js` is a comprehensive example that supports both platforms:
+Define a unified payment configuration object for both platforms, as shown in `App.js`:
 
 ```javascript
-const externalConfig = {
-  amount: '',
-  email: '',
-  isRecurring: false,
-  isAuthenticatedACH: false,
-  isSecureAuthentication: false,
-  isBillingVisible: false,
-  isAdditionalVisible: false,
-  isEmail: true, // Android-specific
-  isEmail: true, // iOS-specific
-  billingInfo: {
+const [amount, setAmount] = useState('5.0');
+const [email, setEmail] = useState('john.doe@example.com');
+const [name, setName] = useState('John Doe');
+const [environment, setEnvironment] = useState('sandbox');
+const [isRecurring, setIsRecurring] = useState(false);
+const [isAuthenticatedACH, setAuthenticatedACH] = useState(true);
+const [isSecureAuthentication, setSecureAuthentication] = useState(true);
+const [isEmail, setIsEmail] = useState(true);
+const [themeConfiguration, setThemeConfiguration] = useState({
+  theme: 'light',
+  bodyBackgroundColor: '#121212',
+  containerBackgroundColor: '#1E1E1E',
+  primaryFontColor: '#FFFFFF',
+  secondaryFontColor: '#B0B0B0',
+  primaryButtonBackgroundColor: '#2563EB',
+  primaryButtonHoverColor: '#1D4ED8',
+  primaryButtonFontColor: '#FFFFFF',
+  secondaryButtonBackgroundColor: '#374151',
+  secondaryButtonHoverColor: '#4B5563',
+  secondaryButtonFontColor: '#E5E7EB',
+  borderRadius: '8',
+  fontSize: '16',
+  fontWeight: 500,
+  fontFamily: '"Inter", sans-serif'
+});
+const [grailPayParams, setGrailPayParams] = useState({
+  role: 'business',
+  timeout: 10,
+  isSandbox: true,
+  brandingName: 'Lyfecycle Payments',
+  finderSubtitle: 'Search for your bank',
+  searchPlaceholder: 'Enter bank name',
+});
+const [recurringData, setRecurringData] = useState({
+  allowCycles: 2,
+  intervals: ['daily', 'weekly', 'monthly'],
+  recurringStartType: 'fixed',
+  recurringStartDate: new Date().toLocaleDateString('en-GB', { day: '2-digit', month: '2-digit', year: 'numeric' }),
+});
+const [paymentConfig, setPaymentConfig] = useState({
+  currency: 'usd',
+  saveCard: true,
+  saveAccount: true,
+  showReceipt: true,
+  showDonate: false,
+  showTotal: true,
+  showSubmitButton: true,
+  paymentMethods: ['card', 'ach'],
+  fields: {
     visibility: { billing: false, additional: false },
-    billing: {
-      address: 'San Fran',
-      country: 'USA',
-      state: 'California',
-      city: 'Paris',
-      postal_code: '234234',
-    },
-    billingRequired: {
-      address: true,
-      country: true,
-      state: true,
-      city: false,
-      postal_code: true,
-    },
-    additional: {
-      name: 'Test User',
-      email_address: 'test@gmail.com',
-      phone_number: '0000000',
-      description: 'Test',
-    },
-    additionalRequired: {
-      name: true,
-      email_address: true,
-      phone_number: true,
-      description: false,
-    },
-  },
-  themeConfiguration: {
-    bodyBackgroundColor: '#1E3A8A',
-    containerBackgroundColor: '#1E40AF',
-    primaryFontColor: '#FFFFFF',
-    secondaryFontColor: '#BFDBFE',
-    primaryButtonBackgroundColor: '#3B82F6',
-    primaryButtonHoverColor: '#2563EB',
-    primaryButtonFontColor: '#FFFFFF',
-    secondaryButtonBackgroundColor: '#1D4ED8',
-    secondaryButtonHoverColor: '#1E40AF',
-    secondaryButtonFontColor: '#FFFFFF',
-    borderRadius: '8',
-    fontSize: '14',
-  },
-  grailPayParams: {
-    role: 'business',
-    timeout: 10,
-    isSandbox: true,
-    brandingName: 'Lyfecycle Payments',
-    finderSubtitle: 'Search for your bank',
-    searchPlaceholder: 'Enter bank name',
+    billing: [
+      { name: 'address', required: true, value: '123 Main Street, Suite 100' },
+      { name: 'country', required: true, value: 'United States' },
+      { name: 'state', required: true, value: 'California' },
+      { name: 'city', required: false, value: 'San Francisco' },
+      { name: 'postal_code', required: true, value: '94105' },
+    ],
+    additional: [
+      { name: 'phone_number', required: false, value: '+1-555-123-4567' },
+      { name: 'description', required: true, value: 'Test payment for development purposes' },
+    ],
   },
-  recurringData: {
-    allowCycles: 2,
-    intervals: ['daily', 'weekly', 'monthly'],
-    recurringStartType:  'custom',
-    recurringStartDate: new Date().toLocaleDateString('en-US', { month: '2-digit', day: '2-digit', year: 'numeric' }),
+});
+const [apiKeys, setApiKeys] = useState({
+  sandbox: {
+    apiKey: 'apiKey',
+    secretKey: 'secretKey',
   },
-  androidConfig: {
-    currency: 'usd',
-    saveCard: true,
-    saveAccount: true,
-    showReceipt: true,
-    showDonate: false,
-    showTotal: true,
-    showSubmitButton: true,
-    paymentMethods: ['card', 'ach'],
-    name: '',
-    fields: {
-      visibility: { billing: false, additional: false },
-      billing: [
-        { name: 'address', required: true, value: 'New Address' },
-        { name: 'country', required: true, value: 'India' },
-        { name: 'state', required: true, value: 'California' },
-        { name: 'city', required: true, value: 'Goa' },
-        { name: 'postal_code', required: true, value: '1432456' },
-      ],
-      additional: [
-        { name: 'name', required: true, value: 'Test User 7' },
-        { name: 'email_address', required: true, value: 'usertest@gmail.com' },
-        { name: 'phone_number', required: true, value: '8978967895' },
-        { name: 'description', required: true, value: 'Hi This is description' },
-      ],
-    },
-    appearanceSettings: {
-      theme: 'dark',
-      bodyBackgroundColor: '#0F5132',
-      containerBackgroundColor: '#166534',
-      primaryFontColor: '#FFFFFF',
-      secondaryFontColor: '#D1FAE5',
-      primaryButtonBackgroundColor: '#059669',
-      primaryButtonHoverColor: '#047857',
-      primaryButtonFontColor: '#FFFFFF',
-      secondaryButtonBackgroundColor: '#065F46',
-      secondaryButtonHoverColor: '#064E3B',
-      secondaryButtonFontColor: '#FFFFFF',
-      borderRadius: '8',
-      fontSize: '14',
-      fontWeight: 500,
-      fontFamily: '"Inter", sans-serif',
-    },
+  staging: {
+    apiKey: 'apiKey',
+    secretKey: 'secretKey',
   },
-};
+});
 ```
 
 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.
+- **Environment**: `sandbox` or `staging` with corresponding API keys.
+- **Payment Options**: Toggles for recurring payments, authenticated ACH, 3D Secure, and email editability.
+- **Billing and Additional Fields**: Configurable fields with visibility and required flags.
+- **Theming**: Unified `themeConfiguration` for both platforms.
+- **GrailPay Params**: Settings for bank search UI.
+- **Recurring Data**: Options for recurring payment cycles, intervals, and start date.
 
 ### 3. Initialize Environment
 
 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') {
+      setIsEnvironmentLoading(true);
       try {
         await EasyMerchantSdk.setViewController();
         await EasyMerchantSdk.configureEnvironment(environment, apiKey, secretKey);
+        console.log(`iOS Environment configured: ${environment} with key ${apiKey}`);
       } catch (err) {
+        console.error('iOS Initialization Error:', err);
         Alert.alert('Error', `Failed to configure iOS environment: ${err.message}`);
+      } finally {
+        setIsEnvironmentLoading(false);
       }
     }
   };
@@ -306,11 +273,58 @@ useEffect(() => {
 }, [environment, apiKeys]);
 ```
 
-**Note**: Replace the placeholder API keys with your actual credentials. Store them securely (e.g., in environment variables) rather than hardcoding.
+**Note**: Replace 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.
+The `buildPaymentConfiguration` function creates a unified configuration object, and the `handlePayment` function validates inputs and delegates to platform-specific handlers. At least one payment method (`card` or `ach`) and a valid amount are required. For recurring payments, at least one interval must be selected.
+
+#### Unified Configuration Builder
+
+```javascript
+const buildPaymentConfiguration = ({
+  amount, environment, paymentConfig, themeConfiguration, grailPayParams,
+  recurringData, isRecurring, isAuthenticatedACH, isSecureAuthentication,
+  email, name, isEmail, metadata, apiKey, secretKey
+}) => {
+  const selectedPaymentMethods = [...paymentConfig.paymentMethods];
+  const config = {
+    environment,
+    amount,
+    currency: 'usd',
+    tokenOnly: false,
+    saveCard: paymentConfig.saveCard,
+    saveAccount: paymentConfig.saveAccount,
+    submitButtonText: 'Submit',
+    authenticatedACH: isAuthenticatedACH,
+    secureAuthentication: isSecureAuthentication,
+    showReceipt: paymentConfig.showReceipt,
+    showDonate: paymentConfig.showDonate,
+    showTotal: paymentConfig.showTotal,
+    showSubmitButton: paymentConfig.showSubmitButton,
+    paymentMethods: selectedPaymentMethods,
+    apiKey,
+    secretKey,
+    fields: {
+      visibility: paymentConfig.fields.visibility,
+      billing: paymentConfig.fields.billing,
+      additional: paymentConfig.fields.additional
+    },
+    appearanceSettings: themeConfiguration,
+    email,
+    name,
+    isEmail,
+    metadata,
+    grailPayParams,
+    is_recurring: isRecurring,
+    numOfCycle: recurringData.allowCycles,
+    recurringIntervals: recurringData.intervals,
+    recurringStartDateType: recurringData.recurringStartType,
+    recurringStartDate: recurringData.recurringStartDate
+  };
+  return config;
+};
+```
 
 #### Main Payment Handler
 
@@ -322,135 +336,70 @@ const handlePayment = async () => {
   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) {
+  if (!paymentConfig.paymentMethods || paymentConfig.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 = [...androidConfig.paymentMethods];
-  const config = {
-    amount,
-    apiKey,
-    secretKey,
-    jsonConfig: {
-      environment,
+    const config = buildPaymentConfiguration({
       amount,
-      tokenOnly: false,
-      currency: androidConfig.currency,
-      saveCard: androidConfig.saveCard,
-      saveAccount: androidConfig.saveAccount,
-      authenticatedACH: isAuthenticatedACH,
-      secureAuthentication: isSecureAuthentication,
-      showReceipt: androidConfig.showReceipt,
-      showDonate: androidConfig.showDonate,
-      showTotal: androidConfig.showTotal,
-      showSubmitButton: androidConfig.showSubmitButton,
-      paymentMethods: selectedPaymentMethods,
-      isEmail,
+      environment,
+      paymentConfig,
+      themeConfiguration,
+      grailPayParams,
+      recurringData,
+      isRecurring,
+      isAuthenticatedACH,
+      isSecureAuthentication,
       email,
       name,
-      fields: {
-        ...androidConfig.fields,
-        visibility: { billing: isBillingVisible, additional: isAdditionalVisible },
-      },
-      metadata: {
-        metaKey: 'metaValue',
-        metaKLey1: 'metaValue1',
-        metaKLey2: 'metaValue2',
-        metaKLey3: 'metaValue3',
-        metaKLey4: 'metaValue4',
-      },
-      ...(isRecurring && {
-        recurring: {
-          enableRecurring: true,
-          recurringData,
-        },
-      }),
-      grailPayParams,
-      appearanceSettings: androidConfig.appearanceSettings,
-    },
-  };
-
-  try {
-    const response = await RNEasymerchantsdk.makePayment(config);
-    const parsedResponse = {
-      ...JSON.parse(response?.response || '{}'),
-      billingInfo: safeParseMaybeJSON(response?.billingInfo),
-      additional_info: safeParseMaybeJSON(response?.additional_info),
-    };
-    setResult(JSON.stringify(parsedResponse, null, 2));
+      isEmail,
+      metadata,
+      apiKey: apiKeys[environment].apiKey,
+      secretKey: apiKeys[environment].secretKey
+    });
+    await handlePlatformPayment(config);
   } catch (error) {
-    setResult(`Error: ${error.message || 'Unknown error'}`);
-    Alert.alert('Payment Error', error.message || 'An error occurred during payment');
+    console.error('Payment Error:', error);
+    setResult(`Error: ${error.message ?? JSON.stringify(error)}`);
+    Alert.alert('Payment Error', error.message ?? 'Unknown error');
+  } finally {
+    clearTimeout(timeoutId);
+    setLoading(false);
   }
 };
 ```
 
-#### iOS Billing
+#### Platform-Specific Payment Handler
 
 ```javascript
-const handleIosBilling = async () => {
-  const selectedPaymentMethodsIOS = androidConfig.paymentMethods.map(method =>
-    method === 'card' ? 'Card' : method === 'ach' ? 'Bank' : method
-  );
+const handlePlatformPayment = async (config) => {
   try {
-    const result = await EasyMerchantSdk.billing(
-      amount,
-      androidConfig.currency || 'usd',
-      billingInfo,
-      selectedPaymentMethodsIOS,
-      themeConfiguration,
-      false,
-      androidConfig.saveCard,
-      androidConfig.saveAccount,
-      isAuthenticatedACH,
-      grailPayParams,
-      'Submit',
-      isRecurring,
-      isRecurring ? recurringData.allowCycles : 0,
-      isRecurring ? recurringData.intervals : [],
-      isRecurring ? recurringData.recurringStartType : '',
-      isRecurring ? recurringData.recurringStartDate : '',
-      isSecureAuthentication,
-      androidConfig.showReceipt,
-      androidConfig.showTotal,
-      androidConfig.showSubmitButton,
-      isEmail,
-      email,
-      name,
-      {
-        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));
+    if (Platform.OS === 'android') {
+      const response = await RNEasymerchantsdk.makePayment(config);
+      const raw = response?.response ? JSON.parse(response.response) : {};
+      const parsedResponse = {
+        ...raw,
+        billingInfo: safeParseMaybeJSON(raw.billingInfo),
+        additional_info: safeParseMaybeJSON(raw.additional_info),
+      };
+      console.log('Android Payment Response:', parsedResponse);
+      setResult(JSON.stringify(parsedResponse, null, 2));
+    } else {
+      const configString = JSON.stringify(config);
+      console.log('iOS Config as String:', configString);
+      const result = await EasyMerchantSdk.billingWithConfig(configString);
+      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 || 'Unknown error'}`);
-    Alert.alert('Billing Error', error.message || 'An error occurred during billing');
+    const platform = Platform.OS === 'android' ? 'Android' : 'iOS';
+    console.error(`${platform} Payment Error:`, error);
+    setResult(`Error: ${error.message ?? JSON.stringify(error)}`);
+    Alert.alert('Payment Error', error.message ?? 'Unknown error');
   }
 };
 ```
@@ -497,7 +446,13 @@ useEffect(() => {
     setResult(JSON.stringify(parsed, null, 2));
   });
   const statusErrorSub = easyMerchantEvents.addListener('PaymentStatusError', (data) => {
-    setResult(`Status Error: ${JSON.stringify(data.error, null, 2)}`);
+    let parsedError = data.error;
+    try {
+      if (typeof parsedError === 'string') {
+        parsedError = JSON.parse(parsedError);
+      }
+    } catch (e) {}
+    setResult(`Status Error: ${JSON.stringify(parsedError, null, 2)}`);
   });
 
   return () => {
@@ -508,20 +463,195 @@ useEffect(() => {
 }, []);
 ```
 
+## UI Components
+
+The `App.js` includes custom UI components to enhance user interaction:
+
+### Dropdown Component
+
+A custom dropdown for selecting options like country or recurring start type, with platform-specific handling for Android (Modal) and iOS (View):
+
+```javascript
+const Dropdown = ({ value, onValueChange, options, placeholder }) => {
+  const [isOpen, setIsOpen] = useState(false);
+  const handleClose = () => setIsOpen(false);
+
+  return (
+    <View style={styles.dropdownContainer}>
+      <TouchableOpacity
+        style={styles.dropdownButton}
+        onPress={() => setIsOpen(!isOpen)}
+      >
+        <Text style={styles.dropdownButtonText}>
+          {value || placeholder}
+        </Text>
+        <Text style={styles.dropdownArrow}>
+          {isOpen ? '▲' : '▼'}
+        </Text>
+      </TouchableOpacity>
+      {Platform.OS === 'android' ? (
+        <Modal
+          visible={isOpen}
+          transparent={true}
+          animationType="fade"
+          onRequestClose={handleClose}
+        >
+          <TouchableWithoutFeedback onPress={handleClose}>
+            <View style={{ flex: 1, backgroundColor: 'rgba(0,0,0,0.2)' }}>
+              <View style={[styles.dropdownOptions, { position: 'absolute', top: '30%', left: 20, right: 20, maxHeight: 300, elevation: 20 }]}>
+                <ScrollView
+                  style={[styles.dropdownScrollView, { maxHeight: 280 }]}
+                  showsVerticalScrollIndicator={true}
+                  persistentScrollbar={true}
+                  nestedScrollEnabled={true}
+                  keyboardShouldPersistTaps="handled"
+                >
+                  {options.map((option, index) => (
+                    <TouchableOpacity
+                      key={index}
+                      style={styles.dropdownOption}
+                      onPress={() => {
+                        onValueChange(option);
+                        setIsOpen(false);
+                      }}
+                    >
+                      <Text style={styles.dropdownOptionText}>{option}</Text>
+                    </TouchableOpacity>
+                  ))}
+                </ScrollView>
+              </View>
+            </View>
+          </TouchableWithoutFeedback>
+        </Modal>
+      ) : (
+        isOpen && (
+          <View style={styles.dropdownOptions}>
+            <ScrollView
+              style={styles.dropdownScrollView}
+              showsVerticalScrollIndicator={true}
+              persistentScrollbar={true}
+              nestedScrollEnabled={true}
+              keyboardShouldPersistTaps="handled"
+            >
+              {options.map((option, index) => (
+                <TouchableOpacity
+                  key={index}
+                  style={styles.dropdownOption}
+                  onPress={() => {
+                    onValueChange(option);
+                    setIsOpen(false);
+                  }}
+                >
+                  <Text style={styles.dropdownOptionText}>{option}</Text>
+                </TouchableOpacity>
+              ))}
+            </ScrollView>
+          </View>
+        )
+      )}
+    </View>
+  );
+};
+```
+
+### Expandable Section Component
+
+A collapsible section for organizing configuration settings:
+
+```javascript
+const ExpandableSection = ({ title, children, isExpanded, onToggle }) => {
+  return (
+    <View style={styles.expandableSection}>
+      <TouchableOpacity
+        style={styles.sectionHeader}
+        onPress={onToggle}
+        activeOpacity={0.7}
+      >
+        <Text style={styles.sectionHeaderTitle}>{title}</Text>
+        <Text style={styles.expandIcon}>
+          {isExpanded ? '▼' : '▶'}
+        </Text>
+      </TouchableOpacity>
+      {isExpanded && (
+        <View style={styles.sectionContent}>
+          {children}
+        </View>
+      )}
+    </View>
+  );
+};
+```
+
+### Filled Button Component
+
+A reusable button component for actions like toggling payment methods or initiating payments:
+
+```javascript
+const FilledButton = ({ title, onPress, disabled = false, style = {}, textStyle = {} }) => {
+  return (
+    <TouchableOpacity
+      style={[
+        styles.filledButton,
+        disabled && styles.filledButtonDisabled,
+        style,
+      ]}
+      onPress={onPress}
+      disabled={disabled}
+    >
+      <Text style={[
+        styles.filledButtonText,
+        disabled && styles.filledButtonTextDisabled,
+        textStyle,
+      ]}>
+        {title}
+      </Text>
+    </TouchableOpacity>
+  );
+};
+```
+
 ## Notes
 
-- **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`.
+- **Billing Info**: Set `paymentConfig.fields.billing` or `additional` to an empty array if not needed. Use `paymentConfig.fields.visibility` to control visibility and `required` flags for field validation.
+- **Payment Methods**:
+  - Android: `['card', 'ach']` (lowercase).
+  - iOS: `['Card', 'Bank']` (capitalized, mapped internally).
+  - Ensure at least one payment method is selected in `paymentConfig.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.
+- **Security**: Store API keys and secret keys securely (e.g., in environment variables or secure storage).
 - **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']`).
+  - **Android**: Uses `RNEasymerchantsdk.makePayment(config)` with a JSON config object.
+  - **iOS**: Uses `EasyMerchantSdk.billingWithConfig(configString)` with a JSON string.
   - iOS supports `paymentReference` for status checks; Android uses `checkPaymentStatus`.
+- **UI Features**:
+  - Expandable sections for configuration management.
+  - Dropdown for selecting countries and recurring start types.
+  - Modal popup to view and confirm configuration before payment.
+  - Color preview for theme configuration inputs.
+  - Secure text entry toggle for secret key input.
 
 ## Troubleshooting
 
-- **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.
+- **iOS Bridge Initialization**:
+  - **Error**: "Failed to retrieve EasyMerchantSdkPlugin instance."
+  - **Solution**: Verify the `easymerchantsdk` pod is installed correctly. Run `pod install --repo-update` and check `AppDelegate.swift` for correct bridge setup.
+- **Android Payment Issues**:
+  - Ensure `paymentConfig.paymentMethods` includes at least one valid method (`['card', 'ach']`).
+  - Validate API keys and secret keys in `apiKeys[environment]`.
+  - Check `gradle.properties` for correct `GITHUB_USERNAME` and `GITHUB_PASSWORD`.
+  - Log the `config` object to verify payment method inclusion (e.g., `console.log(JSON.stringify(config, null, 2))`).
+- **Pod Installation**:
+  - **Error**: `pod install` fails.
+  - **Solution**: Ensure Ruby 3.2.8 or higher is installed and run `pod install --repo-update`.
+- **Payment Failures**:
+  - Check console logs for detailed errors.
+  - Ensure `amount` is a positive number.
+  - Verify at least one payment method is selected.
+  - Confirm API keys match the selected environment (`sandbox` or `staging`).
+- **Payment Method Errors**:
+  - **Issue**: Payment fails due to invalid methods.
+  - **Solution**: Ensure `paymentConfig.paymentMethods` contains valid entries (`['card', 'ach']` for Android, mapped to `['Card', 'Bank']` for iOS) and that ACH-specific settings (`isAuthenticatedACH`, `isSecureAuthentication`) are correctly configured when `ach` is selected.
+- **UI Issues**:
+  - **Dropdown Not Displaying**: Ensure `zIndex` is set correctly for the dropdown container (e.g., `zIndex: 9998`).
+  - **Modal Overlap**: Verify `elevation` and `shadow` properties for Android modals to prevent overlap.
+  - **Keyboard Overlap**: Ensure `KeyboardAvoidingView` is configured with the correct `behavior` and `keyboardVerticalOffset`.