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

$3

``bash
npm install nimbbl-mobile-react-native-sdk


or


yarn add nimbbl-mobile-react-native-sdk
`

$3

`typescript
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: '',
bankCode: '',
walletCode: '',
paymentFlow: ''
});
`

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

$3

| 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 |

$3

| 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 |

$3

| 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

$3

`bash
npm install nimbbl-mobile-react-native-sdk
`

$3

`javascript
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

`javascript
// 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
}
});
`

$3

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

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

API Reference

$3

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

$3

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

`javascript
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

`javascript
try {
const checkoutResult = await nimbblSDK.checkout({
orderToken: 'YOUR_ORDER_TOKEN',
paymentModeCode: '',
bankCode: '',
walletCode: '',
paymentFlow: ''
});
} catch (error) {
// Handle payment error

// Check error codes
if (error.code === ERROR_CODES.PAYMENT_FAILED) {
// Handle payment failure
}
}
`

Platform Setup

$3

1. Install pods:
`bash
cd ios && pod install
`

2. Add to your Info.plist:
`xml
NSAppTransportSecurity

NSAllowsArbitraryLoads


`

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

$3

1. Add to your android/app/build.gradle:
`gradle
android {
defaultConfig {
minSdkVersion 21
}
}
`

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

`

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

Examples

$3

`javascript
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

$3

#### 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:
`bash
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:
`bash
cd android
./gradlew clean
cd ..
npx react-native run-android
`

#### 5. Metro Bundler Issues

Problem: JavaScript bundle fails to load.

Solution:
`bash
npx react-native start --reset-cache
`

$3

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

`javascript
const nimbblSDK = NimbblSDK.getSharedInstance();

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

$3

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 support@nimbbl.biz

License

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

Support

For support, email support@nimbbl.biz or join our Slack channel.

Version Migration

$3

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

`bash


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 nimbbl-mobile-react-native-sdk@1.0.0-alpha.3
`

$3

✅ Stable version is now available!

`bash


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

$3

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

$3

For production applications, consider locking to specific versions:

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

$3

- 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

$3

🚀 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

$3

🚀 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.