@jimrising/easymerchantsdk-react-native 2.1.6 → 2.1.8

package/README.md

@@ -1,15 +1,15 @@
 # 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 a unified configuration structure with minor 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.
+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
 
 - **Node.js and npm**: Version 16 or higher.
-- **React Native Environment**: Set up as per the [official documentation](https://reactnative.dev/docs/environment-setup).
+- **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.
-- **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
 
@@ -19,7 +19,7 @@ Add the EasyMerchant SDK to your `package.json` under `dependencies`:
 
 ```json
 "dependencies": {
-  "@jimrising/easymerchantsdk-react-native": "^2.1.6"
+  "@jimrising/easymerchantsdk-react-native": "^2.1.8"
 }
 ```
 
@@ -50,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
@@ -61,8 +61,9 @@ GITHUB_PASSWORD=your-github-token
 
 ### 3. iOS Configuration
 
-1. **Update AppDelegate.swift**  
-   Modify `ios/AppDelegate.swift` 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
@@ -117,8 +118,9 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
 }
 ```
 
-2. **Update Podfile**  
-   In `ios/Podfile`, add the EasyMerchant SDK pod:
+2. **Update Podfile**
+
+In `ios/Podfile`, add the EasyMerchant SDK pod:
 
 ```ruby
 platform :ios, '16.0'
@@ -138,398 +140,209 @@ pod install --repo-update
 
 ## Usage
 
-The provided `App.js` is a complete implementation showcasing the EasyMerchant SDK's capabilities. 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 configuration object for payment settings. Below is an example based on `App.js`:
+Create a unified `config` object with default values for all required and optional fields.
 
 ```javascript
-const externalConfig = {
-  amount: '',
-  email: '',
-  isRecurring: false,
-  isAuthenticatedACH: false,
-  isSecureAuthentication: false,
-  isBillingVisible: false,
-  isAdditionalVisible: false,
-  emailEditable: true, // Android-specific
-  isEmail: true, // iOS-specific
-  billingInfo: {
-    visibility: { billing: false, additional: false },
-    billing: {
-      address: 'San Fran, Punjab',
-      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: '2140871329',
-      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',
+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 }, // 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' }
+    ],
+    additional: [
+      { name: 'phone_number', required: false, value: '+1-555-123-4567' },
+      { name: 'description', required: true, value: 'Test payment for development purposes' }
+    ]
   },
-  grailPayParams: {
-    role: 'business',
-    timeout: 10,
-    isSandbox: true,
-    brandingName: 'Lyfecycle Payments',
-    finderSubtitle: 'Search for your bank',
-    searchPlaceholder: 'Enter bank name',
+  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
   },
-  recurringData: {
-    allowCycles: 2,
-    intervals: ['daily', 'weekly', 'monthly'],
-    recurringStartType: 'custom',
-    recurringStartDate: new Date().toLocaleDateString('en-US', { month: '2-digit', day: '2-digit', year: 'numeric' }),
+  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
   },
-  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',
-    },
+  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`.
-- **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**: `themeConfiguration` for iOS and `androidConfig.appearanceSettings` for Android.
-- **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.
+**Notes**:
+- Replace `apiKey` and `secretKey` with your actual credentials.
+- Ensure `paymentMethods` includes at least one valid method (`'card'` or `'ach'` for Android; mapped to `'Card'` or `'Bank'` for iOS).
+- 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
-const [apiKeys, setApiKeys] = useState({
-  sandbox: {
-    apiKey: 'your-sandbox-api-key',
-    secretKey: 'your-sandbox-secret-key',
-  },
-  staging: {
-    apiKey: 'your-staging-api-key',
-    secretKey: 'your-staging-secret-key',
-  },
-});
-
-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.
+**Note**: Call `initializeEnvironment()` before processing payments on iOS. Android does not require this step.
 
-### 4. Handle Payments
+### 4. Process Payments
 
-The `handlePayment` function validates inputs and delegates to platform-specific billing 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.
-
-#### 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');
+  // Validate inputs
+  if (!config.amount || isNaN(parseFloat(config.amount)) || parseFloat(config.amount) <= 0) {
+    Alert.alert('Error', 'Please set a valid amount');
+    return;
   }
-  if (isRecurring && (!recurringData.intervals || recurringData.intervals.length === 0)) {
-    return Alert.alert('Error', 'Please select at least one interval for recurring payment');
+  if (!config.paymentMethods || config.paymentMethods.length === 0) {
+    Alert.alert('Error', 'Please select at least one payment method');
+    return;
   }
-  if (!androidConfig.paymentMethods || androidConfig.paymentMethods.length === 0) {
-    return Alert.alert('Error', 'Please select at least one payment method');
+  if (config.is_recurring && (!config.recurringIntervals || config.recurringIntervals.length === 0)) {
+    Alert.alert('Error', 'Please select at least one interval for recurring payment');
+    return;
   }
 
-  setLoading(true);
-  const timeoutId = setTimeout(() => setLoading(false), 3000);
   try {
     if (Platform.OS === 'android') {
-      await handleAndroidBilling();
+      // Android: Pass config object directly
+      const response = await RNEasymerchantsdk.makePayment(config);
+      const raw = response?.response ? JSON.parse(response.response) : {};
+      const parsedResponse = {
+        ...raw,
+        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);
+      Alert.alert('Success', 'Payment processed!');
     } else {
-      await handleIosBilling();
+      // iOS: Initialize environment and pass config as JSON string
+      await initializeEnvironment();
+      const configString = JSON.stringify(config);
+      const result = await EasyMerchantSdk.makePayment(configString);
+      const refToken = result?.additionalInfo?.threeDSecureStatus?.data?.ref_token;
+      console.log('iOS Payment Response:', result);
+      if (refToken) console.log('Reference Token:', refToken);
+      Alert.alert('Success', 'Payment processed!');
     }
-  } finally {
-    clearTimeout(timeoutId);
-    setLoading(false);
-  }
-};
-```
-
-#### Android Billing
-
-```javascript
-const handleAndroidBilling = async () => {
-  const { apiKey, secretKey } = apiKeys[environment];
-  const selectedPaymentMethods = [...androidConfig.paymentMethods];
-  let finalPaymentMethods = selectedPaymentMethods;
-  if (selectedPaymentMethods.length === 1 && selectedPaymentMethods.includes('ach')) {
-    finalPaymentMethods = ['ach'];
-  }
-
-  const config = {
-    amount,
-    apiKey,
-    secretKey,
-    jsonConfig: {
-      environment,
-      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: finalPaymentMethods,
-      ...(finalPaymentMethods.length === 1 && finalPaymentMethods.includes('ach') && {
-        paymentMethods: ['ach'],
-        allowedPaymentMethods: ['ach'],
-        disableCard: true,
-      }),
-      emailEditable,
-      email,
-      name,
-      fields: {
-        ...androidConfig.fields,
-        visibility: { billing: isBillingVisible, additional: isAdditionalVisible },
-      },
-      metadata: {
-        account_id: 1,
-        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 raw = response?.response ? JSON.parse(response.response) : {};
-    const parsedResponse = {
-      ...raw,
-      billingInfo: safeParseMaybeJSON(raw.billingInfo),
-      additional_info: safeParseMaybeJSON(raw.additional_info),
-    };
-    setResult(JSON.stringify(parsedResponse, null, 2));
   } catch (error) {
-    setResult(`Error: ${error.message || 'Unknown error'}`);
-    Alert.alert('Payment Error', error.message || 'An error occurred during payment');
+    console.error(`${Platform.OS === 'android' ? 'Android' : 'iOS'} Payment Error:`, error);
+    Alert.alert('Payment Error', error.message || 'Unknown error');
   }
 };
 ```
 
-#### iOS Billing
-
-```javascript
-const handleIosBilling = async () => {
-  const selectedPaymentMethodsIOS = androidConfig.paymentMethods.map(method =>
-    method === 'card' ? 'Card' : method === 'ach' ? 'Bank' : method
-  );
-
-  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,
-      {
-        account_id: 1,
-        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 || 'Unknown error'}`);
-    Alert.alert('Billing Error', error.message || 'An error occurred during billing');
-  }
-};
-```
-
-#### 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 () => {
@@ -537,35 +350,89 @@ useEffect(() => {
     statusSub.remove();
     statusErrorSub.remove();
   };
-}, []);
+};
+```
+
+**Note**: Call `setupAndroidEventListeners()` during app initialization and clean up listeners when done (returned function).
+
+### 6. Check Payment Status (Android Only)
+
+Check the status of a payment on Android:
+
+```javascript
+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');
+  }
+};
+```
+
+### 7. Payment Reference (iOS Only)
+
+Retrieve payment reference details on iOS using a `ref_token`:
+
+```javascript
+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 `billingInfo` to `null` if not needed. Use `billingRequired` and `additionalRequired` to configure required fields.
 - **Payment Methods**:
-    - Android: `['card', 'ach']` (lowercase).
-    - iOS: `['Card', 'Bank']` (capitalized).
-    - Ensure at least one payment method 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).
+  - Android: Use `['card', 'ach']` (lowercase).
+  - iOS: Methods are mapped to `['Card', 'Bank']` internally.
+  - Ensure at least one method is included in `config.paymentMethods`.
+- **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. Handles payment methods as 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`.
+  - 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**: If "Failed to retrieve EasyMerchantSdkPlugin instance" appears, verify the `easymerchantsdk` pod is installed correctly. Run `pod install --repo-update` and check `AppDelegate.swift` for correct bridge setup.
+- **iOS Bridge Initialization**:
+  - **Error**: "Failed to retrieve EasyMerchantSdkPlugin instance."
+  - **Solution**: Verify `easymerchantsdk` pod installation (`pod install --repo-update`) and check `AppDelegate.swift` for correct bridge setup.
 - **Android Payment Issues**:
-    - Ensure `paymentMethods` includes at least one valid method (`['card', 'ach']`).
-    - Validate API keys and secret keys.
-    - 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**: If `pod install` fails, ensure Ruby 3.2.8 or higher is installed and run `pod install --repo-update`.
+  - 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 `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**: If payment fails due to invalid methods, ensure `androidConfig.paymentMethods` contains valid entries (`['card', 'ach']` for Android, `['Card', 'Bank']` for iOS) and that ACH-specific settings (`authenticatedACH`, `secureAuthentication`) are correctly configured when `ach` is selected.
+  - 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.