react-native-payment-package

A comprehensive, production-ready React Native SDK for seamless payment gateway integration. This package supports a wide range of payment methods including Cards, Net Banking, and native UPI intent handling (PhonePe, Google Pay, Paytm, BHIM, CRED, Amazon Pay).

Table of Contents

1. Prerequisites
2. Installation
3. Configuration
   • iOS Setup
   • Android Setup
4. Implementation Guide
   • Initialization
   • Starting a Payment
   • Handling Responses
5. Platform-Specific Instructions
6. Testing
7. Troubleshooting
8. License

1. Prerequisites

Before integrating the SDK, ensure your environment meets the following requirements:

• React Native: 0.70.0 or higher (Supports New Architecture/TurboModules)
• Node.js: v18 or higher
• Platforms:
  • iOS: Deployment target 13.4 or higher, CocoaPods installed.
  • Android: minSdkVersion 24 or higher, Kotlin support enabled.
• Accounts: An active merchant account with Omniware to obtain your API Key and Salt.

2. Installation

Install the package using your preferred package manager:

# Using yarn
yarn add react-native-payment-package

# Using npm
npm install react-native-payment-package

Note: Peer dependencies like react-native-webview and react-native-safe-area-context are bundled as regular dependencies and will be installed automatically.

Native Installation

iOS

Install the necessary pods:

cd ios && pod install

Android

The package uses Auto-linking. No additional gradle steps are required for basic installation.

3. Configuration

iOS Setup

To support UPI deep-linking (opening PhonePe, GPay, etc.), you must whitelist the URL schemes in your Info.plist:

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>upi</string>
    <string>phonepe</string>
    <string>gpay</string>
    <string>tez</string>
    <string>paytmmp</string>
    <string>paytm</string>
    <string>bhim</string>
    <string>credpay</string>
    <string>amazonpay</string>
    <string>whatsapp</string>
</array>

Android Setup

For Android 11 (API 30) and above, you must declare the queries in your AndroidManifest.xml to detect installed UPI apps:

<queries>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="upi" />
    </intent>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="phonepe" />
    </intent>
    <!-- Add other schemes as needed -->
</queries>

4. Implementation Guide

Initialization

Initialize the PaymentClient with your merchant credentials. It is recommended to do this at the root of your application.

import { PaymentClient } from 'react-native-payment-package';

const client = new PaymentClient({
  apiKey: 'YOUR_API_KEY',
  salt: 'YOUR_MERCHANT_SALT',
  environment: 'TEST', // Use 'LIVE' for production
});

// Initialize in useEffect or at app start
useEffect(() => {
  client.initialize();
}, []);

Starting a Payment

To trigger the payment flow, use the startPayment method. You must also render the PaymentModal component in your view hierarchy to show the payment UI.

import { PaymentModal, type PaymentResponse } from 'react-native-payment-package';

const handlePay = async () => {
  try {
    const response: PaymentResponse = await client.startPayment('https://pgbiz.omniware.in', {
      api_key: 'YOUR_API_KEY',
      order_id: 'ORD_12345',
      mode: 'TEST',
      amount: '100.00',
      currency: 'INR',
      description: 'Product Purchase',
      name: 'John Doe',
      email: '[email protected]',
      phone: '9999999999',
      city: 'Mumbai',
      country: 'India',
      zip_code: '400001',
      return_url: 'https://yourdomain.com/success',
      return_url_failure: 'https://yourdomain.com/failure',
    });

    if (response.status === 'success') {
      console.log('Payment Successful!', response.transactionId);
    } else {
      console.log('Payment Failed:', response.responseMessage);
    }
  } catch (error) {
    console.error('Unexpected Error:', error);
  }
};

// Render this in your main App component or screen
return (
  <>
    <YourContent onPay={handlePay} />
    <PaymentModal />
  </>
);

Handling Responses

The PaymentResponse object provides both mapped fields and the raw gateway response:

| Field | Type | Description | |---|---|---| | status | success | failed | pending | Overall status of the transaction. | | transactionId | string | Gateway transaction reference. | | orderId | string | Your provided order ID. | | responseMessage | string | Human-readable response from the gateway. | | responseJson | any | Full raw JSON response received from the gateway API. |

5. Platform-Specific Instructions

iOS

• Testing: Always test on a physical device to verify UPI app switching. Simulators do not support deep-linking to external apps.
• Common Issue: If canOpenURL returns false for an app that is installed, double-check your LSApplicationQueriesSchemes in Info.plist.

Android

• Testing: Can be tested on emulators with Play Store support (if UPI apps are installed) or physical devices.
• ProGuard: If using ProGuard, ensure you keep the native module classes. The package includes default rules.

6. Testing

Sandbox Environment

Set environment: 'TEST' during initialization and mode: 'TEST' in your payment parameters.

Test Credentials

Use the following credentials for testing in the Sandbox environment:

• Card Number: 4111 1111 1111 1111 (Visa Test)
• Expiry: Any future date
• CVV: 123
• UPI: You can use any valid-looking VPA (e.g., success@upi) in the sandbox environment.

7. Troubleshooting

| Error | Cause | Solution | |---|---|---| | CONFIG_MISSING | initialize() wasn't called. | Call client.initialize() before startPayment(). | | Unsupported URL | iOS scheme missing. | Check LSApplicationQueriesSchemes in Info.plist. | | No UPI App Found | No UPI apps on device. | The SDK will show an alert. Install a UPI app like PhonePe or GPay. | | HASH_MISMATCH | Salt or Key is incorrect. | Verify your Salt and API Key match exactly what is in your dashboard. |

8. Support

For integration support or reporting issues:

• Issues: GitHub Issues
• Email: [email protected]
• Website: omniware.in

License: MIT