react-native-zoho-payments

A React Native plugin for integrating Zoho Payments with support for both Android and iOS platforms. This plugin provides a seamless way to accept payments in your React Native applications using Zoho Payments SDK.

📚 Quick Setup Guide | 🔧 Troubleshooting | 💬 Report Issue

Features

• ✅ Support for both Android and iOS
• ✅ Multiple payment methods (Cards, Net Banking, UPI)
• ✅ Easy-to-use JavaScript API
• ✅ Promise-based async operations
• ✅ Comprehensive error handling
• ✅ TypeScript type definitions (coming soon)

🔥 Quick Fix for Android Build Errors: If you encounter package com.zoho.payment.checkout does not exist, you need to add maven { url 'https://maven.zohodl.com' } to your project's android/build.gradle. See Android Setup section below or the TROUBLESHOOTING.md guide.

Requirements

Android

• Minimum SDK: Android 8 (API level 26)
• Zoho Payments SDK 1.0.0

iOS

• Minimum iOS version: 13.0
• Zoho Payments iOS SDK 1.0.0

React Native

• React Native 0.60+

Installation

Install the package using npm or yarn:

npm install react-native-zoho-payments

or

yarn add react-native-zoho-payments

iOS Setup

1. Navigate to your iOS directory and install CocoaPods dependencies:

cd ios
pod install
cd ..

2. Ensure your Podfile has the minimum iOS version set to 13.0:

platform :ios, '13.0'

Android Setup

1. IMPORTANT: Add the Zoho Maven repository to your project-level android/build.gradle file:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://maven.zohodl.com' }  // Add this line
    }
}

For React Native 0.73+ using settings.gradle:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://maven.zohodl.com' }  // Add this line
    }
}

2. Ensure your android/build.gradle has the minimum SDK version:

buildscript {
    ext {
        minSdkVersion = 26  // Must be 26 or higher
    }
}

3. Make sure you have internet permission in your AndroidManifest.xml (usually already present):

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

4. After adding the repository, clean and rebuild:

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

⚠️ Common Issue: If you get "package com.zoho.payment.checkout does not exist" error, see the TROUBLESHOOTING.md guide.

Usage

1. Import the Plugin

import { ZohoPayments, PaymentMethod } from 'react-native-zoho-payments';

2. Initialize the SDK

Initialize the Zoho Payments SDK with your API credentials. This should be done once when your app starts:

import { useEffect } from 'react';

useEffect(() => {
  initializeZohoPayments();
}, []);

const initializeZohoPayments = async () => {
  try {
    await ZohoPayments.initialize('YOUR_API_KEY', 'YOUR_ACCOUNT_ID');
    console.log('Zoho Payments initialized successfully');
  } catch (error) {
    console.error('Failed to initialize Zoho Payments:', error);
  }
};

3. Create a Payment Session

Important: Payment session must be created from your backend server by calling the Zoho Payments API. Never create payment sessions directly from your mobile app for security reasons.

Backend API call example:

POST https://payments.zoho.in/api/v1/paymentsession
Content-Type: application/json
Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN

{
  "amount": 1000,
  "currency": "INR",
  "customer": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "9876543210"
  }
}

See Zoho Payments API Documentation for complete API reference.

4. Show the Checkout Widget

Once you have the payment session ID from your backend, show the checkout widget:

const handlePayment = async () => {
  try {
    const result = await ZohoPayments.showCheckout({
      paymentSessionId: 'session_id_from_backend',
      description: 'Payment for Order #123',
      invoiceNumber: 'INV-001',
      referenceNumber: 'REF-001',
      name: 'John Doe',
      email: 'john@example.com',
      phone: '9876543210',
      paymentMethod: PaymentMethod.UPI, // Optional: pre-select payment method
    });

    // Payment successful
    console.log('Payment successful:', result);
    console.log('Payment ID:', result.paymentId);
    console.log('Signature:', result.signature);
    
    // Verify the payment on your backend
    await verifyPaymentOnBackend(result.paymentId, result.signature);
    
  } catch (error) {
    // Payment failed or was cancelled
    console.error('Payment failed:', error.message);
  }
};

5. Verify Payment

Always verify the payment status on your backend server using the Payment Retrieve API:

GET https://payments.zoho.in/api/v1/payment/{paymentId}
Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN

API Reference

ZohoPayments.initialize(apiKey, accountId)

Initialize the Zoho Payments SDK.

Parameters:

• apiKey (string, required): Your Zoho Payments API key
• accountId (string, required): Your Zoho Payments account ID

Returns: Promise<void>

Example:

await ZohoPayments.initialize('your_api_key', 'your_account_id');

---

ZohoPayments.showCheckout(options)

Show the Zoho Payments checkout widget.

Parameters:

• options (object, required):
  • paymentSessionId (string, required): Payment session ID obtained from backend
  • description (string, optional): Description of the payment (max 500 characters)
  • invoiceNumber (string, optional): Invoice number (max 50 characters)
  • referenceNumber (string, optional): Reference number for the payment
  • name (string, optional): Customer name
  • email (string, optional): Customer email address
  • phone (string, optional): Customer phone number
  • paymentMethod (string, optional): Pre-selected payment method (see PaymentMethod enum)

Returns: Promise<PaymentResult>

PaymentResult Object:

{
  paymentId: string,    // Unique payment identifier
  signature: string,    // Payment signature for verification
  status: 'success'     // Payment status
}

Throws: Error if payment fails or is cancelled

Example:

const result = await ZohoPayments.showCheckout({
  paymentSessionId: 'session_id',
  description: 'Premium subscription',
  name: 'Jane Smith',
  email: 'jane@example.com',
  phone: '9876543210',
  paymentMethod: PaymentMethod.CARD,
});

---

PaymentMethod (Enum)

Available payment methods:

• PaymentMethod.CARD - Credit/Debit cards
• PaymentMethod.NET_BANKING - Net banking
• PaymentMethod.UPI - UPI payments

Example:

import { PaymentMethod } from 'react-native-zoho-payments';

// Use in showCheckout
await ZohoPayments.showCheckout({
  // ... other options
  paymentMethod: PaymentMethod.UPI,
});

Complete Example

Here's a complete example of integrating Zoho Payments in your React Native app:

import React, { useState, useEffect } from 'react';
import { View, Button, Alert } from 'react-native';
import { ZohoPayments, PaymentMethod } from 'react-native-zoho-payments';

const PaymentScreen = () => {
  const [isInitialized, setIsInitialized] = useState(false);

  useEffect(() => {
    initializeSDK();
  }, []);

  const initializeSDK = async () => {
    try {
      await ZohoPayments.initialize(
        'your_api_key',
        'your_account_id'
      );
      setIsInitialized(true);
    } catch (error) {
      Alert.alert('Error', 'Failed to initialize payment SDK');
    }
  };

  const createPaymentSession = async () => {
    // Call your backend API to create a payment session
    const response = await fetch('https://your-backend.com/api/create-payment', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        amount: 1000,
        currency: 'INR',
      }),
    });
    
    const data = await response.json();
    return data.paymentSessionId;
  };

  const handlePayment = async () => {
    if (!isInitialized) {
      Alert.alert('Error', 'SDK not initialized');
      return;
    }

    try {
      // Step 1: Get payment session from backend
      const paymentSessionId = await createPaymentSession();

      // Step 2: Show checkout
      const result = await ZohoPayments.showCheckout({
        paymentSessionId: paymentSessionId,
        description: 'Product purchase',
        name: 'Customer Name',
        email: 'customer@example.com',
        phone: '9876543210',
        paymentMethod: PaymentMethod.UPI,
      });

      // Step 3: Verify on backend
      await verifyPayment(result.paymentId, result.signature);

      Alert.alert('Success', `Payment completed! ID: ${result.paymentId}`);
    } catch (error) {
      Alert.alert('Payment Failed', error.message);
    }
  };

  const verifyPayment = async (paymentId, signature) => {
    // Verify payment on your backend
    await fetch('https://your-backend.com/api/verify-payment', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ paymentId, signature }),
    });
  };

  return (
    <View style={{ padding: 20 }}>
      <Button
        title="Pay Now"
        onPress={handlePayment}
        disabled={!isInitialized}
      />
    </View>
  );
};

export default PaymentScreen;

Error Handling

The plugin throws errors with descriptive messages. Always wrap payment calls in try-catch blocks:

try {
  await ZohoPayments.showCheckout(options);
} catch (error) {
  switch (error.message) {
    case 'PAYMENT_FAILED':
      // Handle payment failure
      break;
    case 'ACTIVITY_ERROR':
      // Android: Activity not available
      break;
    case 'VIEW_CONTROLLER_ERROR':
      // iOS: View controller not available
      break;
    default:
      // Handle other errors
      console.error('Payment error:', error.message);
  }
}

Security Best Practices

1. Never expose API keys in client code: Store them securely on your backend
2. Create payment sessions on backend: Always create payment sessions from your secure server
3. Verify signatures: Always verify payment signatures on your backend after successful payment
4. Use HTTPS: Ensure all API calls to your backend use HTTPS
5. Validate on server: Never trust client-side payment status alone; always verify with Zoho Payments API

Troubleshooting

🚨 Common Android Build Error

Error: package com.zoho.payment.checkout does not exist

Solution: This is the most common issue. You MUST add the Zoho Maven repository to your project's android/build.gradle:

allprojects {
    repositories {
        maven { url 'https://maven.zohodl.com' }  // Required!
    }
}

Then clean and rebuild:

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

📖 For detailed troubleshooting, see TROUBLESHOOTING.md

Android Issues

Issue: SDK initialization fails

Solution: Ensure the Zoho Payments Maven repository is accessible:

maven { url 'https://maven.zohodl.com' }

Issue: Build fails with dependency conflicts

Solution: Check that your minSdkVersion is at least 26.

iOS Issues

Issue: Pod install fails

Solution: Try the following:

cd ios
rm -rf Pods Podfile.lock
pod install

Issue: Module not found

Solution: Clean and rebuild:

cd ios
xcodebuild clean
cd ..
npx react-native run-ios

General Issues

Issue: Payment widget doesn't show

Solution:

• Ensure SDK is initialized before calling showCheckout()
• Verify the payment session ID is valid
• Check that the current activity/view controller is available

Issue: "Another checkout is already in progress"

Solution: Only one checkout can be active at a time. Wait for the previous checkout to complete or fail.

Example App

A complete example app demonstrating the integration is available in the /example directory.

To run the example:

cd example

# Install dependencies
npm install

# Run on Android
npm run android

# Run on iOS
cd ios
pod install
cd ..
npm run ios

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Resources

• Zoho Payments Documentation
• Zoho Payments Android Integration
• Zoho Payments iOS Integration
• Zoho Payments API Reference

Support

For issues related to:

• This plugin: Open an issue on GitHub
• Zoho Payments SDK: Contact Zoho Support at support@zohopayments.com or call 1800 309 8845 (India)
• Zoho Payments API: Refer to Zoho Payments API Documentation

License

MIT

Disclaimer

This is an unofficial React Native plugin for Zoho Payments. It is not officially maintained or supported by Zoho Corporation. Use at your own discretion.

Changelog

1.0.0

• Initial release
• Support for Android and iOS
• Support for Card, Net Banking, and UPI payment methods
• Promise-based API
• Example app included