Zoho Payments React Native SDK

A React Native library for integrating Zoho Payments checkout into your Android and iOS apps. Accept payments via cards, net banking, and UPI with a pre-built, secure checkout UI.

Features

• Pre-built checkout UI — no need to build payment forms
• Supports Card, Net Banking, and UPI payment methods
• Sandbox and Live environments for testing and production
• US and India domain support
• TypeScript types for options and results

Requirements

| Platform | Minimum Version | | ----------- | ---------------- | | React Native | 0.72+ | | Android | minSdkVersion 26 (Android 8.0)+ | | iOS | 15.6+ | | Node | >= 18 |

Installation

npm install zoho-payments-react-native-sdk
# or
yarn add zoho-payments-react-native-sdk

Android setup

The SDK depends on Zoho's Android SDK hosted on a custom Maven repository. Add it to your app's Android config.

Option A: android/build.gradle (project-level)

In buildscript.repositories and allprojects.repositories, add:

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

Option B: android/settings.gradle (if you use dependencyResolutionManagement)

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

If your app uses both files for repos, add the Zoho repo in both. Ensure minSdkVersion is at least 26.

iOS setup

Since ZohoPayments-pod is not on the CocoaPods trunk, add the Zoho spec repo source at the top of your ios/Podfile alongside the default CDN source. Ensure the platform is iOS 15.6 or higher.

source 'https://github.com/zoho/zpayments-ios-sdk.git'
source 'https://cdn.cocoapods.org/'

platform :ios, '15.6'

target 'YourApp' do
  config = use_native_modules!

  pod 'ZohoPayments-pod', '1.0.3'

  use_react_native!(...)
end

Then run:

cd ios && pod install && cd ..

Alternative: xcframework (manual linking)

If you prefer to link the native SDK manually instead of via CocoaPods:

1. Copy ZohoPayments.xcframework into your project (e.g. ios/Frameworks/ZohoPayments.xcframework).
2. Open your .xcworkspace in Xcode, select your app target, go to General → Frameworks, Libraries, and Embedded Content, click +, and add the xcframework with Embed & Sign.
3. Build (Cmd+B). The Swift bridge imports ZohoPayments; linking the xcframework provides that module.

Quick Start

import { initialize, showCheckout } from 'zoho-payments-react-native-sdk';

// 1. Initialize with your credentials (once at app startup)
initialize('your_api_key', 'your_account_id', 'india', 'live');

// 2. Show checkout and handle the result
const result = await showCheckout({
  paymentSessionId: 'your_payment_session_id',
  description: 'Order payment',
});

console.log('Payment ID:', result.paymentId);
console.log('Signature:', result.signature);

Usage

Step 1: Obtain credentials

Get your API Key and Account ID from the Zoho Payments Dashboard.

Step 2: Create a payment session

Create a payment session on your backend using the Payments Session API. The API returns a payment_session_id that you pass to the SDK.

Step 3: Initialize the SDK

Call initialize() before showing checkout. This sets up the SDK with your merchant credentials, domain, and environment. Both domain and environment default to 'india' and 'live' respectively if omitted.

import { initialize } from 'zoho-payments-react-native-sdk';

initialize(
  'your_api_key',
  'your_account_id',
  'india',     // 'india' | 'us' — defaults to 'india'
  'live',      // 'live' | 'sandbox' — defaults to 'live'
);

Step 4: Configure checkout options

Pass the payment session ID and optional fields to showCheckout():

const result = await showCheckout({
  paymentSessionId: 'ps_xxxxxxxxxxxxxxx',
  description: 'Order #1234',
  invoiceNumber: 'INV-1234',
  referenceNumber: 'REF-5678',
  name: 'John Doe',
  email: '[email protected]',
  phone: '+919876543210',
  paymentMethod: 'upi',   // optional: 'card' | 'netbanking' | 'upi'
});

Step 5: Handle the result

showCheckout() returns a result object on success or throws on failure/cancel:

try {
  const result = await showCheckout({ paymentSessionId: '...' });
  console.log('Payment ID:', result.paymentId);
  console.log('Signature:', result.signature);
  if (result.mandateId) console.log('Mandate ID:', result.mandateId);
  // Verify the signature on your backend before fulfilling the order
} catch (e: any) {
  console.log('Error:', e?.code, e?.message);
}

API Reference

| Method | Description | |--------|-------------| | initialize(apiKey, accountId, domain?, environment?) | Call once at app startup. Required before showCheckout. Sets the merchant credentials, domain, and environment. | | showCheckout(options) | Opens the native checkout UI. Returns a Promise with { status, paymentId, signature, mandateId? } on success; throws on failure or user cancel. |

initialize parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | apiKey | string | Yes | Your Zoho Payments API key | | accountId | string | Yes | Your Zoho Payments account ID | | domain | 'india' \| 'us' | No | Defaults to 'india' | | environment | 'live' \| 'sandbox' | No | Defaults to 'live' |

showCheckout options:

| Option | Type | Required | Description | |--------|------|----------|-------------| | paymentSessionId | string | Yes | Session ID from your backend | | description | string | No | Payment description | | invoiceNumber | string | No | Invoice reference | | referenceNumber | string | No | Order reference | | name | string | No | Customer name | | email | string | No | Customer email | | phone | string | No | Customer phone | | paymentMethod | 'card' \| 'netbanking' \| 'upi' | No | Pre-select a payment method |

Troubleshooting

Android

• "Could not find com.zoho.paymentsdk:paymentsdk:…" Add maven { url 'https://maven.zohodl.com' } in both android/build.gradle and, if present, android/settings.gradle.

• minSdkVersion / manifest merger errors Set minSdkVersion to at least 26 in your app's android/build.gradle.

iOS

• "dyld: Library not loaded" or app crashes on launch Ensure you added source 'https://github.com/zoho/zpayments-ios-sdk.git' at the top of your Podfile, added the pod 'ZohoPayments-pod' line inside your target, and ran pod install.

• "no such module 'ZohoPayments'" Verify both source lines are at the top of your Podfile (the Zoho source and https://cdn.cocoapods.org/) and the pod is declared in your target. Then clean and reinstall:

  cd ios && pod deintegrate && pod install && cd ..

Quick Reference

| Platform | Steps | |----------|-------| | Install | npm install zoho-payments-react-native-sdk | | Android | Add maven { url 'https://maven.zohodl.com' } in build.gradle / settings.gradle; minSdk 26 | | iOS | Add both source lines at top of Podfile; add pod 'ZohoPayments-pod', '1.0.3' in target; run pod install |

License

MIT License. See LICENSE for details.