## Zoho Payments Documentation Index

Access the complete documentation index at:
https://www.zoho.com/in/payments/llms.txt

Use this file to discover all available documentation pages before proceeding.

# React Native Integration

Zoho Payments provides a React Native SDK to securely collect payments in your cross-platform app for iOS and Android. React Native integration allows your app to communicate with Zoho Payments, handle transactions, and manage checkout flows across platforms using a pre-built, secure checkout UI.

**Prerequisites:**

*   **React Native:** 0.72 or higher
*   **Android:** minSdkVersion 26 or higher
*   **iOS:** 15.6 or higher
*   **Node:** 18 or higher

### Platform Requirements for Android

Before using the SDK, ensure your project is properly configured so it functions correctly on Android and supports all required dependencies:

1.  Set `minSdkVersion` to 26 or higher in `android/app/build.gradle`.
2.  Add the Zoho Maven repository in `android/build.gradle`:

Install SDK - Project Level

Copy

```javascript
allprojects {
    repositories {
        maven { url 'https://maven.zohodl.com' }
    }
}
```

### Platform Requirements for iOS

1.  Go to your project’s root directory and run `cd ios && pod install`.
2.  Add the below snippet inside the app target’s **Podfile**.

iOS - Podfile Configuration

Copy

```ruby
source 'https://github.com/zoho/zpayments-ios-sdk.git'
```

3.  Run `pod install` again to apply the changes.

*   [Add React Native SDK](#Add-the-dependency)
*   [Create Payment Session](#Create-Payment-Session)
*   [Integrate SDK](#Integrate-the-SDK)
*   [Invoke Checkout Widget](#Launch-checkout)
*   [Handle Payment Result](#Handle-Result)
*   [Confirm Payment](#Confirm-payment)
*   [Verify Payment Status](#Verify-status)

## 1\. Add React Native SDK

To begin the integration, add the Zoho Payments React Native SDK to your application.

Install via npm

Copy

```bash
npm install zoho-payments-react-native-sdk
```

Or using Yarn:

Install via Yarn

Copy

```bash
yarn add zoho-payments-react-native-sdk
```

## 2\. Create Payment Session

To initiate the payment process, you need to create a payment session. Based on your payment type, you can create the session for one-time or recurring payments.

One-Time PaymentsRecurring Payments

### Payment Session for One-time Payments

To invoke the checkout widget, you need to obtain the `paymentSessionId`. To do this:

*   Collect payment information from your app (amount, currency, etc.).
*   Call the [Payment Session Create API.](https://www.zoho.com/in/payments/api/v1/payment-session/#create-payment-session "payment session")

The API will return a `paymentSessionId`. Use this ID to invoke the checkout widget and initiate the payment process.

### Create Customer

Collect customer details (name, email, phone, and metadata) and call the [Create Customer API.](https://www.zoho.com/in/payments/api/v1/mandates/#create-customer "Create Customer") The API will return a `customer_id`, which you can use to initiate a payment session for mandate enrollment.

### Create Payment Session for Mandate Enrollment

Call the [Create Payment Session for Mandate Enrollment API](https://www.zoho.com/in/payments/api/v1/mandates/#create-payment-session-mandate-enrollment "Mandate Enrollment") on your server using an OAuth token to obtain a `payment_session_id.`

**Note:** Each session allows up to three payment attempts, but only one can succeed. Any additional attempts return an `invalid_payment_session` response.

Use the `payment_session_id` when invoking the checkout widget.

**Note:** Payment sessions must always be created from your server to keep your API credentials secure. Do not make this API call from the client side.

## 3\. Integrate SDK

To integrate the SDK and enable payment processing in your React Native application, you need to configure and initialize it within your project. The SDK provides methods to initialize, launch checkout, and handle payment results. Here are the main SDK methods you’ll use:

**Method**

**Description**

`initialize(apiKey, accountId, domain, environment)`

Initialize SDK with merchant credentials. This is required before checkout.

`showCheckout(options)`

Opens the payment checkout UI with the provided options. Returns a result object on success or throws on failure.

### Import the SDK

Import the `initialize` and `showCheckout` methods from the SDK.

Import SDK

Copy

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

### Initialize SDK

Initialize the SDK with your **API Key, Account ID, Domain**, and **Environment** before invoking the checkout widget. This is required before starting any checkout process.

Initialize SDK

Copy

```typescript
initialize('YOUR_API_KEY', 'YOUR_ACCOUNT_ID', 'india', 'live');
```

**Note:** You can find your API key and account ID in the Zoho Payments [web app](https://payments.zoho.in/).

### Configure checkout options

Set up the checkout options by providing your payment session details along with the customer’s information as shown below:

Checkout Options

Copy

```typescript
const options = {
  paymentSessionId: 'YOUR_PAYMENT_SESSION_ID',   // Required
  description: 'Order #12345',                   // Optional
  invoiceNumber: 'INV-001',                      // Optional
  referenceNumber: 'REF-001',                    // Optional
  name: 'John Doe',                              // Optional
  email: 'john@example.com',                     // Optional
  phone: '+919876543210',                        // Optional
  paymentMethod: 'upi'                           // Optional: 'card' | 'netbanking' | 'upi'

};
```

## 4\. Invoke Checkout Widget

Invoke the checkout widget to initiate the payment process. Use the sandbox environment for testing, and switch to production when you’re ready to go live.

Invoke Checkout Widget

Copy

```typescript
try {
  const result = await showCheckout({
  paymentSessionId: 'ps_1234567890',
  description: 'Order #12345',
  name: 'John Doe',
  email: 'john@example.com',
  phone: '+919876543210',
  paymentMethod: 'upi',

  });

  // Payment succeeded
  console.log('Payment ID:', result.paymentId);
  console.log('Signature:', result.signature);
  if (result.mandateId) {
    console.log('Mandate ID:', result.mandateId);
  }
} catch (e: any) {
  // Payment failed or cancelled
  console.log('Error Code:', e?.code);
  console.log('Error Message:', e?.message);
}
```

If you’re facing any errors while processing payments via mobile app, refer to the [error messages](https://www.zoho.com/in/payments/developerdocs/mobile-errors/ "error messages") to identify and resolve the issue.

## 5\. Handle Payment Result

After calling `showCheckout`, the SDK returns a success result upon completion or throws an error if the payment fails.

**Payment Result**

**Fields**

**Description**

**Success**

`paymentId`, `signature`, `mandateId?`

Returned when the payment is completed successfully. `paymentId` is the unique identifier, `signature` is used for server-side verification, and `mandateId` is included for recurring or mandate-based payments.

**Failure**

`code`, `message`

Returned when the payment fails or is cancelled. Use `code` and `message` to identify and handle the error appropriately.

## 6\. Confirm the Payment

Once the customer completes the payment, the SDK will return a `paymentId` and `signature`. Send these to your backend server to confirm the payment and update your system.

**Note:** In some cases, you may not receive the `paymentId` if the customer accidentally closes the widget before a response is returned. In such cases, use your configured webhooks or the `paymentSessionId` to retrieve the payment status.

## 7\. Verify Payment Status

You can verify your payment status in three ways:

*   **Verify via Widget Response:** After receiving the `paymentId`, verify the payment status using the [Payment Retrieve API](https://www.zoho.com/in/payments/api/v1/payments/#retrieve-payment-details "Retrieve API"). For recurring payments, use the [Retrieve Mandate API](https://www.zoho.com/in/payments/api/v1/mandates/#retrieve-mandate "Retrieve Mandate") to check specific mandates. Based on the status returned (success, failure, or pending), update your system.
    
*   **Verify via Webhooks:** Use your [configured webhooks](/in/payments/developerdocs/webhooks/configure/ "configure-webhooks") for the events **payment.success** and **payment.failed** to receive the final payment status directly.
    
*   **Verify via Session ID:** If you haven’t received the payment status via the widget response or webhooks, use the [Payment Session Retrieve API](https://www.zoho.com/in/payments/api/v1/payment-session/#retrieve-payment-session "Session") to verify the payment result.
    

**Note:** Ensure that all three options are configured for reliable payment verification.