Onramp React Native SDK

A React Native SDK for seamless payment integration using WebView.

📦 How to Install

Run the following command to install the latest version of the SDK package:

npm install onramp-native-sdk

Required Peer Dependencies

Make sure the following libraries are installed in your project before using the SDK, as they are required peer dependencies:

npm install react-native-webview react-native-device-info
# or
yarn add react-native-webview react-native-device-info

Note: These libraries are not bundled with the SDK to prevent version conflicts. Please ensure you install compatible versions in your app.

How to Import

After installing the package, import it where needed:

import PaymentsWebView from 'onramp-native-sdk';

How to Use the SDK to Render the Widget

This is the view container that holds the PaymentsWebView widget:

return (
  <View style={styles.container}>
    <PaymentsWebView
      ref={paymentRef}
      token={token}
      type={projectType}
      appEnv={appEnvironment}
      onClose={handleClose}
      onSuccess={handleSuccess}
      onError={handleError}
    />
  </View>
);

Example Usage (App.tsx)

Implement the following logic and provide the required parameters: token, projectType, and appEnvironment.

import React, { useState, useRef, useEffect } from 'react';
import { View, Alert, AppState, Linking, StyleSheet } from 'react-native';
import PaymentsWebView from 'onramp-native-sdk';

const App = () => {
  const [isVisible, setIsVisible] = useState(false);
  const [token, setToken] = useState('');
  const paymentRef = useRef(null);

  const projectType = 'cli';
  const appEnvironment = 'production';

  // Handle app resume after external redirect (e.g., BankID)
  useEffect(() => {
    const handleAppStateChange = async (state) => {
      if (state === 'active') {
        const url = await Linking.getInitialURL();
        if (url?.includes('ridmpaymentsapp://')) {
          Alert.alert('Returned from BankID', url);
          setIsVisible(false);
        }
      }
    };

    const subscription = AppState.addEventListener('change', handleAppStateChange);
    return () => subscription.remove();
  }, []);

  // Set token (retrieve once from backend and inject into frontend)
  useEffect(() => {
    setToken('abc'); // Replace this with your actual backend-generated token
  }, []);

  // Event handlers
  const handleClose = () => {
    Alert.alert('Closed', 'Payment modal closed');
    setIsVisible(false);
  };

  const handleSuccess = () => {
    Alert.alert('Success');
    setIsVisible(false);
  };

  const handleError = () => {
    Alert.alert('Error');
    setIsVisible(false);
  };

  return (
    <View style={styles.container}>
      <PaymentsWebView
        ref={paymentRef}
        token={token}
        type={projectType}
        appEnv={appEnvironment}
        onClose={handleClose}
        onSuccess={handleSuccess}
        onError={handleError}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

export default App;

Get Token API (Server-to-Server Only)

Important: This API must be called from your backend only. Do NOT integrate this endpoint directly into your frontend.

Endpoint:

POST {{your-url}}/backend/api/sdk/v1/token

Headers:

Content-Type: application/json
api-key: {{apiKey}}

Example Response:

{
  "code": 200,
  "status": true,
  "message": "Success",
  "data": {
    "sua_token": "xyz"
  }
}

How to Run the Application

Getting Started

Ensure you have completed the setup steps above before running the app.

Step 1: Start Metro Server

Metro is the JavaScript bundler for React Native.

# Using npm
npm start

# OR using Yarn
yarn start

Step 2: Run on Android

# Using npm
npx react-native run-android
# OR
npm run android

# Using Yarn
yarn android

Step 2: Run on iOS

For iOS, install CocoaPods dependencies (run only on first setup or when native dependencies change):

bundle install
bundle exec pod install

Then run the app:

# Using npm
npx react-native run-ios
# OR
npm run ios

# Using Yarn
yarn ios

For help with CocoaPods, visit the CocoaPods Getting Started Guide.

Step 3: Modify Your App

Make changes in App.tsx. Your app will auto-refresh on save.

✅ Congratulations! 🎉 You've successfully integrated and run the Onramp React Native SDK! Happy coding! 🚀