Nimbbl React Native SDK

✅ Stable Release v1.3.2 - Production Ready!

A comprehensive React Native SDK for integrating Nimbbl payment gateway into your mobile applications. This SDK provides a seamless bridge between React Native and native payment functionality, offering a unified API for both iOS and Android platforms.

✨ Key Features

• 🚀 Easy Integration - Simple setup and initialization with production-ready defaults
• 💳 Multiple Payment Methods - Support for cards, UPI, netbanking, wallets, EMI, and cash
• 🌐 WebView Integration - Built-in payment webview with customization options
• 🔗 Robust Bridge - Seamless communication between React Native and native SDKs
• 📱 Cross Platform - Identical behavior on both iOS and Android
• 🛡️ Type Safety - Comprehensive TypeScript definitions for better development experience
• 📊 Production Ready - Built-in analytics, logging, and error handling
• 🔄 Unified Event Handling - Single callback system for all payment responses
• 🎯 Latest Native SDKs - Built on iOS 2.0.16 and Android 4.0.9

🚀 Quick Start

Installation

npm install nimbbl-mobile-react-native-sdk
# or
yarn add nimbbl-mobile-react-native-sdk

Basic Integration

import { NimbblSDK } from 'nimbbl-mobile-react-native-sdk';

const nimbblSDK = NimbblSDK.getSharedInstance();

// Initialize with default production configuration
await nimbblSDK.initialize();

// Set up payment response handler
nimbblSDK.addCheckoutResponseListener((data) => {
  if (data.status === 'success') {
    console.log('Payment successful:', data);
  } else {
    console.log('Payment failed:', data);
  }
});

// Start payment with all optional parameters
await nimbblSDK.checkout({
  orderToken: 'YOUR_ORDER_TOKEN', 
  paymentModeCode: '<OPTIONAL>', 
  bankCode: '<OPTIONAL>', 
  walletCode: '<OPTIONAL>', 
  paymentFlow: '<OPTIONAL>' 
});

That's it! Your payment integration is complete. 🎉

📚 Documentation

• Sample App - Complete working example with React Navigation
• Simple Integration Guide - Step-by-step merchant integration
• BUILD.md - Development build guide
• SETUP.md - Comprehensive development setup

📋 System Requirements

React Native Version Support

| React Native Version | Support Status | Notes | |----------------------|----------------|-------| | ^0.70.0 | ✅ Supported | Minimum supported version | | ^0.71.0 | ✅ Supported | Recommended version | | ^0.72.0 | ✅ Supported | Recommended version | | ^0.73.0 | ✅ Supported | Latest stable version | | ^0.74.0 | ✅ Supported | Latest stable version | | ^0.75.0 | ✅ Supported | Latest stable version | | ^0.76.0 | ✅ Recommended | Latest stable version |

Node.js Version Support

| Node.js Version | Support Status | Notes | |-----------------|----------------|-------| | ^16.0.0 | ✅ Supported | Minimum supported version | | ^18.0.0 | ✅ Supported | Recommended version | | ^20.0.0 | ✅ Supported | Latest LTS version | | ^21.0.0 | ✅ Supported | Latest stable version |

Platform Support

| Platform | Support Status | Minimum Version | |----------|----------------|-----------------| | Android | ✅ Supported | API Level 21 (Android 5.0) | | iOS | ✅ Supported | iOS 13.0+ |

🎯 Why Choose Nimbbl React Native SDK?

• ✅ Stable Release: Production-ready SDK with comprehensive testing and bug fixes
• ✅ Production Ready: Thoroughly tested and optimized for production environments
• ✅ Cross-Platform Consistency: Identical behavior on iOS and Android
• ✅ Latest Native SDKs: Built on the most recent iOS (2.0.16) and Android (4.0.9) SDKs
• ✅ TypeScript First: Full TypeScript support with comprehensive type definitions
• ✅ Simple Integration: Get started in minutes with our straightforward API

🚀 Getting Started

1. Install the SDK

npm install nimbbl-mobile-react-native-sdk

2. Import and Initialize

import { NimbblSDK } from 'nimbbl-mobile-react-native-sdk';

const nimbblSDK = NimbblSDK.getSharedInstance();

// Initialize with default production configuration
await nimbblSDK.initialize();

// OR initialize with custom configuration
await nimbblSDK.initialize({
  api_base_url: 'https://api.nimbbl.tech/',
  app_code: 'your_custom_app_code' // Optional: defaults to 'reactnative_webview_sdk'
});

3. Set Up Payment Response Handler

// Set up unified payment response handler
nimbblSDK.addCheckoutResponseListener((data) => {
  if (data.status === 'success') {
    console.log('Payment successful:', data);
    // Handle successful payment
  } else {
    console.log('Payment failed:', data);
    // Handle failed payment
  }
});

4. Start Payment

// Start payment with all optional parameters
await nimbblSDK.checkout({
  orderToken: 'YOUR_ORDER_TOKEN',
  paymentModeCode: '<OPTIONAL>',
  bankCode: '<OPTIONAL>',
  walletCode: '<OPTIONAL>', 
  paymentFlow: '<OPTIONAL>'
});

That's it! Your payment integration is complete. 🎉

API Reference

NimbblSDK

The main SDK class that provides all payment functionality.

Methods

• getSharedInstance() - Get shared SDK instance (singleton pattern)
• initialize() - Initialize the SDK with default configuration
• checkout(options) - Process payment with order token
• addCheckoutResponseListener(callback) - Add unified checkout response listener (recommended)
• removeCheckoutResponseListener(callback) - Remove checkout response listener

Event Handling

The SDK uses a unified event handling approach for payment responses:

import { NimbblSDK } from 'nimbbl-mobile-react-native-sdk';

const nimbblSDK = NimbblSDK.getSharedInstance();

// Initialize SDK
await nimbblSDK.initialize();

// Use unified checkout response listener
nimbblSDK.addCheckoutResponseListener((data) => {
  if (data.status === 'success') {
    // Handle successful payment
    // Handle success - navigate to success screen
  } else {
    // Handle failed payment
    // Handle failure - show error message
  }
});

// Optional: Clean up listeners when done
// nimbblSDK.removeCheckoutResponseListener(callback);

Error Handling

try {
  const checkoutResult = await nimbblSDK.checkout({
    orderToken: 'YOUR_ORDER_TOKEN',
    paymentModeCode: '<OPTIONAL>',
    bankCode: '<OPTIONAL>',
    walletCode: '<OPTIONAL>',
    paymentFlow: '<OPTIONAL>'
  });
} catch (error) {
  // Handle payment error
  
  // Check error codes
  if (error.code === ERROR_CODES.PAYMENT_FAILED) {
    // Handle payment failure
  }
}

Platform Setup

iOS

1. Install pods:

cd ios && pod install

2. Add to your Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

Note: The iOS implementation is written in Swift for modern, type-safe development.

Android

1. Add to your android/app/build.gradle:

android {
    defaultConfig {
        minSdkVersion 21
    }
}

2. Add to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

Note: The Android implementation is written in Kotlin for modern, type-safe development.

Examples

Complete Payment Flow

import { NimbblSDK, EVENTS } from 'nimbbl-mobile-react-native-sdk';

class PaymentManager {
  constructor() {
    this.nimbblSDK = NimbblSDK.getSharedInstance();
  }

  async initialize() {
    await this.nimbblSDK.initialize();
  }

  setupEventListeners() {
    // Use unified checkout response listener
    this.nimbblSDK.addCheckoutResponseListener((data) => {
      if (data.status === 'success') {
        // Handle successful payment
        // Navigate to success screen
      } else {
        // Handle failed payment
        // Show error message
      }
    });
  }

  async processPayment(orderToken) {
    try {
      // Process payment using the order token
      const result = await this.nimbblSDK.checkout({
        orderToken: orderToken,
        paymentModeCode: '',
        bankCode: '',
        walletCode: '',
        paymentFlow: ''
      });
      
      return { success: true, result };
    } catch (error) {
      return { success: false, error: error.message };
    }
  }
}

Troubleshooting

Common Issues

1. Payment Status Screen Not Opening (iOS)

Problem: WebView opens and closes, but payment status screen doesn't appear.

Solution:

• Ensure you're using the latest SDK version (^1.3.2)
• The SDK automatically manages event listeners - no manual setup required
• Check that your app properly handles the payment success/failure events

2. Event Listeners Not Working

Problem: Payment events are not being received.

Solution:

• The SDK automatically sets up event listeners during initialization
• Make sure to call initialize() before using the SDK
• Event listeners are managed internally for optimal performance

3. iOS Build Issues

Problem: Build fails with missing native modules.

Solution:

cd ios
rm -rf build
rm -rf ~/Library/Developer/Xcode/DerivedData/*
pod install
cd ..
npx react-native run-ios

4. Android Build Issues

Problem: Build fails with Gradle errors.

Solution:

cd android
./gradlew clean
cd ..
npx react-native run-android

5. Metro Bundler Issues

Problem: JavaScript bundle fails to load.

Solution:

npx react-native start --reset-cache

Debug Mode

For debugging purposes, you can check the SDK initialization status and handle errors appropriately:

const nimbblSDK = NimbblSDK.getSharedInstance();

try {
  await nimbblSDK.initialize();
  // SDK initialized successfully
} catch (error) {
  // Handle initialization error
}

Getting Help

If you encounter issues not covered here:

1. Check the sample app for implementation examples
2. Review the API documentation above
3. Contact support at [email protected]

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, email [email protected] or join our Slack channel.

Version Migration

Upgrading Between Alpha Versions

When upgrading between alpha versions, check the changelog for breaking changes:

# Check current version
npm list nimbbl-mobile-react-native-sdk

# Upgrade to latest alpha
npm install nimbbl-mobile-react-native-sdk@latest

# Or upgrade to specific version
npm install [email protected]

Migration from Alpha to Stable

✅ Stable version is now available!

# Upgrade to latest stable version
npm install nimbbl-mobile-react-native-sdk@^1.3.2

# Update your package.json
# Change from: "nimbbl-mobile-react-native-sdk": "^1.0.0-alpha.12"
# To: "nimbbl-mobile-react-native-sdk": "^1.3.2"

Key Changes in Stable Versions:

• ✅ Automatic Event Listener Management: SDK automatically manages event listeners for optimal performance
• ✅ Simplified Integration: No need to manually add/remove event listeners
• ✅ Enhanced Error Handling: Improved error messages and debugging capabilities
• ✅ Production Ready: Fully tested and optimized for production use
• ✅ Updated Native SDKs: Latest iOS (2.0.16) and Android (4.0.9) SDK integrations

Breaking Changes Migration

For major version updates (e.g., 1.x to 2.x):

1. Check the migration guide in the release notes
2. Update your code according to the breaking changes
3. Test thoroughly before deploying to production

Version Locking

For production applications, consider locking to specific versions:

{
  "dependencies": {
    "nimbbl-mobile-react-native-sdk": "1.3.2"
  }
}

Deprecation Policy

• Alpha versions: Features may be deprecated without notice
• Stable versions: Deprecated features will be marked with warnings for at least one minor version
• Major versions: Breaking changes will be clearly documented

📝 Release Notes

v1.3.2 - Stable Release ✅

🚀 Stable Production-Ready React Native SDK for Nimbbl Payments

🔧 Updates & Fixes

• Updated iOS Native SDK: Upgraded to iOS SDK v2.0.16 for improved stability and features
• Updated Android Native SDK: Upgraded to Android SDK v4.0.9 for enhanced performance
• Podspec Improvements: Updated podspec configuration for better CocoaPods integration
• Test Fixes: Fixed test expectations to match actual SDK behavior
• Code Quality: Improved code formatting and linting compliance

✨ Features

• Unified API: Single API for both iOS and Android platforms
• Latest Native SDKs: Built on iOS 2.0.16 and Android 4.0.9
• TypeScript Support: Full TypeScript definitions for better development experience
• Cross-Platform Consistency: Identical behavior on iOS and Android
• Production Ready: Optimized for production environments with comprehensive error handling

🛠️ Technical Highlights

• Modern Architecture: Built with React Native best practices
• Native Bridge: Seamless communication between React Native and native SDKs
• Performance Optimized: Efficient memory management and callback handling
• Clean Codebase: Production-ready code with no debug artifacts
• Comprehensive Testing: Full test coverage with 20+ test cases (all passing)

📱 Platform Support

• iOS: iOS 13.0+ with Swift implementation
• Android: API Level 21+ (Android 5.0) with Kotlin implementation
• React Native: 0.70.0+ support with 0.76.0 recommended

v1.3.0 - Initial Stable Release 🎉

🚀 Production-Ready React Native SDK for Nimbbl Payments

✨ Features

• Unified API: Single API for both iOS and Android platforms
• Latest Native SDKs: Built on iOS 2.0.7 and Android 4.0.4
• TypeScript Support: Full TypeScript definitions for better development experience
• Cross-Platform Consistency: Identical behavior on iOS and Android
• Production Ready: Optimized for production environments with comprehensive error handling

🔧 Core Functionality

• Easy Integration: Simple setup with production-ready defaults
• Multiple Payment Methods: Support for cards, UPI, netbanking, wallets, EMI, and cash
• WebView Integration: Built-in payment webview with customization options
• Unified Event Handling: Single callback system for all payment responses
• Robust Error Handling: Comprehensive error handling and fallback mechanisms

🛠️ Technical Highlights

• Modern Architecture: Built with React Native best practices
• Native Bridge: Seamless communication between React Native and native SDKs
• Performance Optimized: Efficient memory management and callback handling
• Clean Codebase: Production-ready code with no debug artifacts
• Comprehensive Testing: Full test coverage with 20+ test cases

🎯 What's Next?

Future releases will include:

• 🔄 Enhanced Features: Additional payment methods and customization options
• 🚀 Performance Improvements: Optimizations based on real-world usage
• 🛠️ Developer Experience: Enhanced debugging tools and documentation
• 📱 Platform Updates: Support for new React Native versions and platform features

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.