@jimrising/easymerchantsdk-react-native 2.1.7 → 2.1.9

package/README.md

@@ -1,7 +1,6 @@
 # EasyMerchant SDK React Native Integration
 
-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.
-
+This guide provides instructions for integrating the EasyMerchant SDK into a React Native application for Android and iOS platforms. It focuses on creating a unified configuration object and using it to process payments with `RNEasymerchantsdk.makePayment` (Android) and `EasyMerchantSdk.makePayment` (iOS). The configuration supports card payments, ACH transfers, recurring payments, 3D Secure authentication, and customizable billing/additional fields.
 
 ## Prerequisites
 
@@ -10,7 +9,7 @@ This guide provides step-by-step instructions for integrating the EasyMerchant S
 - **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.
+- **EasyMerchant SDK Credentials**: Obtain API keys and secret keys for `sandbox` or `production` environments.
 
 ## Installation
 
@@ -20,7 +19,7 @@ Add the EasyMerchant SDK to your `package.json` under `dependencies`:
 
 ```json
 "dependencies": {
-  "@jimrising/easymerchantsdk-react-native": "^2.1.7"
+  "@jimrising/easymerchantsdk-react-native": "^2.1.9"
 }
 ```
 
@@ -51,7 +50,7 @@ allprojects {
 }
 ```
 
-2. Define `GITHUB_USERNAME` and `GITHUB_PASSWORD` in `android/gradle.properties` or your CI/CD system. For example:
+2. Define `GITHUB_USERNAME` and `GITHUB_PASSWORD` in `android/gradle.properties`:
 
 ```properties
 GITHUB_USERNAME=your-github-username
@@ -141,318 +140,209 @@ pod install --repo-update
 
 ## Usage
 
-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.
+This section explains how to configure and process payments using a unified configuration object, passed to `RNEasymerchantsdk.makePayment` (Android) or `EasyMerchantSdk.makePayment` (iOS). The configuration includes all necessary fields with default values, supporting card payments, ACH transfers, recurring payments, and 3D Secure authentication.
 
 ### 1. Import Required Modules
 
-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 { NativeModules, Platform, Alert } from 'react-native';
 const { RNEasymerchantsdk, EasyMerchantSdk } = NativeModules;
 ```
 
 ### 2. Define Configuration
 
-Define a unified payment configuration object for both platforms, as shown in `App.js`:
+Create a unified `config` object with default values for all required and optional fields.
 
 ```javascript
-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'],
+const config = {
+  environment: 'sandbox', // String, e.g., 'sandbox' or 'production'
+  amount: '5.0', // String or number, must be a positive value
+  currency: 'usd', // String, currency code, e.g., 'usd'
+  tokenOnly: false, // Boolean, set to true for tokenization only, false for full payment
+  saveCard: true, // Boolean, set to true to save card details, false otherwise
+  saveAccount: true, // Boolean, set to true to save account details for ACH, false otherwise
+  submitButtonText: 'Submit', // String, text for the payment button
+  authenticatedACH: true, // Boolean, set to true to enable authenticated ACH, false otherwise
+  secureAuthentication: true, // Boolean, set to true to enable 3D Secure, false otherwise
+  showReceipt: true, // Boolean, set to true to show receipt after payment, false otherwise
+  showDonate: false, // Boolean, set to true to show donation option, false otherwise
+  showTotal: true, // Boolean, set to true to display total amount, false otherwise
+  showSubmitButton: true, // Boolean, set to true to show submit button, false otherwise
+  paymentMethods: ['card', 'ach'], // Array of strings, must include at least one method, e.g., ['card', 'ach']
+  apiKey: 'replace-with-api-key', // String, environment-specific API key
+  secretKey: 'replace-with-secret-key', // String, environment-specific secret key
   fields: {
-    visibility: { billing: false, additional: false },
+    visibility: { billing: false, additional: false }, // Object, visibility for fields
     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' },
+      { 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' },
-    ],
+      { name: 'description', required: true, value: 'Test payment for development purposes' }
+    ]
   },
-});
-const [apiKeys, setApiKeys] = useState({
-  sandbox: {
-    apiKey: 'apiKey',
-    secretKey: 'secretKey',
+  appearanceSettings: {
+    theme: 'light', // String, UI theme, e.g., 'light' or 'dark'
+    bodyBackgroundColor: '#121212', // String, hex color for body background
+    containerBackgroundColor: '#1E1E1E', // String, hex color for container background
+    primaryFontColor: '#FFFFFF', // String, hex color for primary font
+    secondaryFontColor: '#B0B0B0', // String, hex color for secondary font
+    primaryButtonBackgroundColor: '#2563EB', // String, hex color for primary button
+    primaryButtonHoverColor: '#1D4ED8', // String, hex color for primary button hover
+    primaryButtonFontColor: '#FFFFFF', // String, hex color for primary button font
+    secondaryButtonBackgroundColor: '#374151', // String, hex color for secondary button
+    secondaryButtonHoverColor: '#4B5563', // String, hex color for secondary button hover
+    secondaryButtonFontColor: '#E5E7EB', // String, hex color for secondary button font
+    borderRadius: '8', // String, border radius in pixels
+    fontSize: '16', // String, font size in pixels
+    fontWeight: 500, // Number, font weight, e.g., 400, 500, 700
+    fontFamily: '"Inter", sans-serif' // String, font family
   },
-  staging: {
-    apiKey: 'apiKey',
-    secretKey: 'secretKey',
+  email: 'john.doe@example.com', // String, customer email
+  name: 'John Doe', // String, customer name
+  isEmail: true, // Boolean, set to true to allow email editing, false otherwise
+  metadata: {
+    metadataOne: 'metadataOne', // String, custom metadata key-value
+    metadataTwo: 'metadataTwo' // String, custom metadata key-value
   },
-});
+  grailPayParams: {
+    role: 'business', // String, GrailPay role
+    timeout: 10, // Number, timeout in seconds
+    isSandbox: true, // Boolean, set to true for GrailPay sandbox mode
+    brandingName: 'Lyfecycle Payments', // String, branding name
+    finderSubtitle: 'Search for your bank', // String, bank finder subtitle
+    searchPlaceholder: 'Enter bank name' // String, search placeholder
+  },
+  is_recurring: false, // Boolean, set to true to enable recurring payments
+  numOfCycle: 2, // Number, minimum 2 cycles for recurring payments
+  recurringIntervals: ['daily', 'weekly', 'monthly'], // Array of strings, intervals for recurring payments
+  recurringStartDateType: 'fixed', // String, recurring start type, e.g., 'fixed' or 'custom'
+  recurringStartDate: '28/08/2025' // String, recurring start date in DD/MM/YYYY format
+};
 ```
 
-This configuration includes:
-- **Basic Info**: `amount`, `email`, `name`.
-- **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.
+**Notes**:
+- Replace `apiKey` and `secretKey` with your actual credentials.
+- Ensure `paymentMethods` includes at least one valid method (`'card'` or `'ach'` ).
+- For recurring payments, set `is_recurring: true` and ensure `recurringIntervals` has at least one interval (`'daily'`, `'weekly'`, `'monthly'`).
+- Set `fields.billing` and `fields.additional` to empty arrays (`[]`) if not needed.
+- Adjust `appearanceSettings` colors to match your app’s design.
+- Store sensitive data like `apiKey` and `secretKey` securely (e.g., in environment variables).
 
-### 3. Initialize Environment
+### 3. Initialize Environment (iOS Only)
 
-Configure the SDK environment (`sandbox` or `staging`) with API keys and secret keys:
+For iOS, configure the environment before processing payments:
 
 ```javascript
-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);
-      }
-    }
-  };
-  updateEnvironment();
-}, [environment, apiKeys]);
+const initializeEnvironment = async () => {
+  try {
+    await EasyMerchantSdk.setViewController();
+    await EasyMerchantSdk.configureEnvironment(config.environment, config.apiKey, config.secretKey);
+    console.log(`iOS Environment configured: ${config.environment}`);
+  } catch (error) {
+    console.error('iOS Initialization Error:', error);
+    Alert.alert('Error', `Failed to configure iOS environment: ${error.message}`);
+  }
+};
 ```
 
-**Note**: Replace placeholder API keys with your actual credentials. Store them securely (e.g., in environment variables) rather than hardcoding.
-
-### 4. Handle Payments
-
-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
+**Note**: Call `initializeEnvironment()` before processing payments on iOS. Android does not require this step.
 
-```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;
-};
-```
+### 4. Process Payments
 
-#### Main Payment Handler
+Use the `config` object to initiate payments. The process differs slightly by platform:
 
 ```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');
+  // Validate inputs
+  if (!config.amount || isNaN(parseFloat(config.amount)) || parseFloat(config.amount) <= 0) {
+    Alert.alert('Error', 'Please set a valid amount');
+    return;
   }
-  if (!paymentConfig.paymentMethods || paymentConfig.paymentMethods.length === 0) {
-    return Alert.alert('Error', 'Please select at least one payment method');
+  if (!config.paymentMethods || config.paymentMethods.length === 0) {
+    Alert.alert('Error', 'Please select at least one payment method');
+    return;
   }
-
-  setLoading(true);
-  const timeoutId = setTimeout(() => setLoading(false), 3000);
-  try {
-    const config = buildPaymentConfiguration({
-      amount,
-      environment,
-      paymentConfig,
-      themeConfiguration,
-      grailPayParams,
-      recurringData,
-      isRecurring,
-      isAuthenticatedACH,
-      isSecureAuthentication,
-      email,
-      name,
-      isEmail,
-      metadata,
-      apiKey: apiKeys[environment].apiKey,
-      secretKey: apiKeys[environment].secretKey
-    });
-    await handlePlatformPayment(config);
-  } catch (error) {
-    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);
+  if (config.is_recurring && (!config.recurringIntervals || config.recurringIntervals.length === 0)) {
+    Alert.alert('Error', 'Please select at least one interval for recurring payment');
+    return;
   }
-};
-```
-
-#### Platform-Specific Payment Handler
 
-```javascript
-const handlePlatformPayment = async (config) => {
   try {
     if (Platform.OS === 'android') {
+      // Android: Pass config object directly
       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),
+        billingInfo: raw.billingInfo ? JSON.parse(raw.billingInfo) : raw.billingInfo,
+        additional_info: raw.additional_info ? JSON.parse(raw.additional_info) : raw.additional_info
       };
       console.log('Android Payment Response:', parsedResponse);
-      setResult(JSON.stringify(parsedResponse, null, 2));
+      Alert.alert('Success', 'Payment processed!');
     } else {
+      // iOS: Initialize environment and pass config as JSON string
+      await initializeEnvironment();
       const configString = JSON.stringify(config);
-      console.log('iOS Config as String:', configString);
-      const result = await EasyMerchantSdk.billingWithConfig(configString);
+      const result = await EasyMerchantSdk.makePayment(configString);
       const refToken = result?.additionalInfo?.threeDSecureStatus?.data?.ref_token;
-      if (refToken) setReferenceToken(refToken);
-      setResult(JSON.stringify(result, null, 2));
+      console.log('iOS Payment Response:', result);
+      if (refToken) console.log('Reference Token:', refToken);
+      Alert.alert('Success', 'Payment processed!');
     }
   } catch (error) {
-    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');
+    console.error(`${Platform.OS === 'android' ? 'Android' : 'iOS'} Payment Error:`, error);
+    Alert.alert('Payment Error', error.message || 'Unknown error');
   }
 };
 ```
 
-#### Helper Function for JSON Parsing
-
-```javascript
-const safeParseMaybeJSON = (value) => {
-  if (typeof value === 'string') {
-    try {
-      return JSON.parse(value);
-    } catch (e) {
-      console.warn('Failed to parse JSON string:', value);
-      return value;
-    }
-  }
-  return value;
-};
-```
+**How It Works**:
+- **Android**: Pass the `config` object to `RNEasymerchantsdk.makePayment(config)`. The response may include `billingInfo` and `additional_info`, which are parsed if they are JSON strings.
+- **iOS**: Stringify the `config` (`JSON.stringify(config)`) and pass to `EasyMerchantSdk.makePayment(configString)`. Call `initializeEnvironment()` first. The response may include a `ref_token` for 3D Secure transactions.
+- **Validation**: Ensures `amount` is positive, at least one payment method is selected, and recurring payments have at least one interval.
+- **Error Handling**: Displays user-friendly alerts for errors.
 
 ### 5. Android Event Listeners
 
 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 setupAndroidEventListeners = () => {
+  if (Platform.OS !== 'android' || !RNEasymerchantsdk) {
+    console.warn('RNEasymerchantsdk not available or not Android.');
+    return () => {};
   }
 
   const easyMerchantEvents = new NativeEventEmitter(RNEasymerchantsdk);
   const successSub = easyMerchantEvents.addListener('PaymentSuccess', (data) => {
     const parsed = JSON.parse(data.response || '{}');
-    setResult(JSON.stringify({
+    const result = {
       ...parsed,
-      billingInfo: safeParseMaybeJSON(parsed.billingInfo),
-      additional_info: safeParseMaybeJSON(parsed.additional_info),
-    }, null, 2));
+      billingInfo: parsed.billingInfo ? JSON.parse(parsed.billingInfo) : parsed.billingInfo,
+      additional_info: parsed.additional_info ? JSON.parse(parsed.additional_info) : parsed.additional_info
+    };
+    console.log('Payment Success:', result);
+    Alert.alert('Success', 'Payment processed!');
   });
+
   const statusSub = easyMerchantEvents.addListener('PaymentStatus', (data) => {
     const parsed = JSON.parse(data.statusResponse || '{}');
-    setResult(JSON.stringify(parsed, null, 2));
+    console.log('Payment Status:', parsed);
+    Alert.alert('Status', JSON.stringify(parsed));
   });
+
   const statusErrorSub = easyMerchantEvents.addListener('PaymentStatusError', (data) => {
     let parsedError = data.error;
     try {
-      if (typeof parsedError === 'string') {
-        parsedError = JSON.parse(parsedError);
-      }
+      if (typeof parsedError === 'string') parsedError = JSON.parse(parsedError);
     } catch (e) {}
-    setResult(`Status Error: ${JSON.stringify(parsedError, null, 2)}`);
+    console.error('Payment Status Error:', parsedError);
+    Alert.alert('Status Error', JSON.stringify(parsedError));
   });
 
   return () => {
@@ -460,198 +350,87 @@ useEffect(() => {
     statusSub.remove();
     statusErrorSub.remove();
   };
-}, []);
-```
-
-## 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
+**Note**: Call `setupAndroidEventListeners()` during app initialization and clean up listeners when done (returned function).
+
+### 6. Check Payment Status (Android Only)
 
-A collapsible section for organizing configuration settings:
+Check the status of a payment on Android:
 
 ```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>
-  );
+const checkPaymentStatus = async () => {
+  if (Platform.OS !== 'android') {
+    Alert.alert('Error', 'Payment status check is Android-only');
+    return;
+  }
+  try {
+    const response = await RNEasymerchantsdk.checkPaymentStatus();
+    console.log('Payment Status:', response);
+    Alert.alert('Status', JSON.stringify(response));
+  } catch (error) {
+    console.error('Status Check Error:', error);
+    Alert.alert('Status Check Error', error.message || 'Unknown error');
+  }
 };
 ```
 
-### Filled Button Component
+### 7. Payment Reference (iOS Only)
 
-A reusable button component for actions like toggling payment methods or initiating payments:
+Retrieve payment reference details on iOS using a `ref_token`:
 
 ```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>
-  );
+const checkPaymentReference = async (refToken) => {
+  if (Platform.OS !== 'ios') {
+    Alert.alert('Error', 'Payment reference is iOS-only');
+    return;
+  }
+  try {
+    const response = await EasyMerchantSdk.paymentReference(refToken);
+    console.log('Payment Reference:', response);
+    Alert.alert('Payment Reference', JSON.stringify(response));
+  } catch (error) {
+    console.error('Payment Reference Error:', error);
+    Alert.alert('Payment Reference Error', error.message || 'Unknown error');
+  }
 };
 ```
 
 ## Notes
 
-- **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).
+  - Use `['card', 'ach']` (lowercase).
+- **Recurring Payments**: Set `is_recurring: true` and include at least one interval in `recurringIntervals`.
+- **Security**: Store `apiKey` and `secretKey` securely (e.g., in environment variables) and ensure they match the `environment`.
+- **Optional Fields**: Set `fields.billing` and `fields.additional` to `[]` if not needed. Use `fields.visibility` to control display.
+- **Theming**: Customize `appearanceSettings` for UI consistency. Ensure hex colors are valid.
+- **GrailPay**: Configure `grailPayParams` for bank search UI (used with ACH payments).
 - **Platform Differences**:
-  - **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.
+  - Android uses a direct object for `makePayment`; iOS requires a JSON string for `makePayment`.
+  - iOS requires environment initialization before payment.
+  - Android supports event listeners; iOS uses direct method responses.
 
 ## Troubleshooting
 
 - **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.
+  - **Solution**: Verify `easymerchantsdk` pod installation (`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]`.
+  - Ensure `config.paymentMethods` includes valid methods (`['card', 'ach']`).
+  - Validate `apiKey` and `secretKey` in `config`.
   - 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))`).
+  - Log `config` for debugging: `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`.
+  - Check console logs for errors.
+  - Verify `amount` is positive and `paymentMethods` is not empty.
+  - Ensure `apiKey` and `secretKey` match the `environment`.
+  - For recurring payments, confirm `recurringIntervals` has at least one entry.
+- **ACH Payments**:
+  - Ensure `authenticatedACH` and `secureAuthentication` are set appropriately in `config` when using `ach`.
+- **Response Parsing**:
+  - Android responses may include JSON strings in `billingInfo` and `additional_info`; parse them as shown.
+  - iOS responses may include a `ref_token` for 3D Secure; store it for reference checks.

package/ios/Classes/EasyMerchantSdk.m

@@ -29,7 +29,7 @@ RCT_EXPORT_METHOD(configureEnvironment:(NSString *)env
 }
 
 RCT_EXPORT_METHOD(
-    billingWithConfig:(NSString *)jsonConfig
+    makePayment:(NSString *)jsonConfig
     resolver:(RCTPromiseResolveBlock)resolve
     rejecter:(RCTPromiseRejectBlock)reject
 )
@@ -38,7 +38,7 @@ RCT_EXPORT_METHOD(
         self.sdkPluginInstance = [[EasyMerchantSdkPlugin alloc] init];
     }
     @try {
-        [self.sdkPluginInstance billingWithConfig:jsonConfig
+        [self.sdkPluginInstance makePayment:jsonConfig
                                         resolver:^(id result) {
                                             resolve(result);
                                             self.sdkPluginInstance = nil;
@@ -48,7 +48,7 @@ RCT_EXPORT_METHOD(
                                             self.sdkPluginInstance = nil;
                                         }];
     } @catch (NSException *exception) {
-        reject(@"BRIDGE_ERROR", [NSString stringWithFormat:@"Failed to call billingWithConfig: %@", exception.reason], nil);
+        reject(@"BRIDGE_ERROR", [NSString stringWithFormat:@"Failed to call makePayment: %@", exception.reason], nil);
     }
 }
 

package/ios/Classes/EasyMerchantSdk.swift

@@ -58,8 +58,8 @@ public class EasyMerchantSdkPlugin: NSObject, RCTBridgeModule {
         EnvironmentConfig.configure(apiKey: apiKey, apiSecret: apiSecret)
     }
 
-    // MARK: - billingWithConfig(...) Exposed to RN - Unified Config Method
-    @objc public func billingWithConfig(
+    // MARK: - makePayment(...) Exposed to RN - Unified Config Method
+    @objc public func makePayment(
         _ jsonConfig: String,
         resolver: @escaping RCTPromiseResolveBlock,
         rejecter: @escaping RCTPromiseRejectBlock

package/ios/easymerchantsdk.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name             = 'easymerchantsdk'
-  s.version          = '2.1.7'
+  s.version          = '2.1.9'
   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.7",
+  "version": "2.1.9",
   "description": "",
   "main": "index.js",
   "scripts": {