Ramp SDK for React Native

Overview

A lightweight React Native SDK that opens the Paybis Partner Widget in a secure in-app browser overlay (no embedded WebView/HTML injection).

Installation

Run the following command:

yarn add @paybis/widget-sdk-react-native

Overlay provider (recommended)

This library uses an adapter approach:

Expo apps: uses expo-web-browser (works in Expo Go)
- Bare RN apps: uses react-native-inappbrowser-reborn if installed
  - Fallback: Linking.openURL (external browser)

Expo

npx expo install expo-web-browser

Bare React Native

yarn add react-native-inappbrowser-reborn cd ios && pod install && cd ..

Quick Start

Open the widget

import React from 'react';
    import { Button, View } from 'react-native';
    import {
    openPaybisWidget,
    type PaybisWidgetDetails,
    type PaybisWidgetEvent,
    } from 'paybis-widget-sdk-react-native';
    
    export default function App() {
        const details: PaybisWidgetDetails = {
            // minimal: requestId OR partnerId
            requestId: 'REQUEST_ID_FROM_BACKEND',
        
            // optional
            locale: 'en',
        };
    
        const onEvent = (e: PaybisWidgetEvent) => {
            console.log('[PaybisWidget event]', e);
        };
        
        const open = async () => {
            const result = await openPaybisWidget(details, {
                env: 'sandbox',
                onEvent,
            });
        
            console.log('[PaybisWidget result]', result);
        };
    
        return (
            <View style={{ padding: 16 }}>
                <Button title="Open Paybis" onPress={open} />
            </View>
        );
    }

API

openPaybisWidget(details, options)

import type {
    PaybisWidgetDetails,
    PaybisWidgetOpenOptions,
    PaybisWidgetResult,
} from 'paybis-widget-sdk-react-native';

export function openPaybisWidget(
    details: PaybisWidgetDetails,
    openOpts?: PaybisWidgetOpenOptions
): Promise<PaybisWidgetResult>;

PaybisWidgetOpenOptions

Field: env
Type: "sandbox" | "prod"
Default: "sandbox"
Description: Environment domain selection

Field: widgetBaseUrl
Type: string
Default: —
Description: Override widget base URL (no trailing slash recommended)

Field: inAppBrowserOptions
Type: Record<string, any>
Default: —
Description: Passed to react-native-inappbrowser-reborn if present

Field: expoWebBrowserOptions
Type: Record<string, any>
Default: —
Description: Passed to expo-web-browser if present

Field: onEvent
Type: (event: PaybisWidgetEvent) => void
Default: —
Description: Event stream callback

Result (PaybisWidgetResult)

Field: type
Type: "success" | "closed" | "opened_external"
Description: Final outcome

Field: openedUrl
Type: string
Description: The URL that was opened

Field: returnedUrl
Type: string?
Description: Redirect URL (if captured)

Field: used
Type: "inappbrowser" | "expo_web_browser" | "linking"
Description: Which mechanism was used

Events

export type PaybisWidgetEvent =
| { type: 'onopen'; payload: { url: string } }
| { type: 'onclose'; payload: { url?: string } }
| { type: 'onredirect'; payload: { url: string } }
| { type: 'onsuccessReturn'; payload: { url: string } }
| { type: 'onfailureReturn'; payload: { url: string } }
| { type: 'onerror'; payload: { message: string; url?: string } };

Widget Params (PaybisWidgetDetails)

All optional. To start you need requestId OR partnerId.

export type PaybisWidgetDetails = {
    partnerId?: string;
    requestId?: string;
    oneTimeToken?: string;
    signature?: string;
    locale?: string;
    indexPage?: string;
    layout?: string;
    transactionFlow?: string;
    partnerUserId?: string;
    cryptoAddress?: string;
    currencyCodeTo?: string;
    currencyCodeFrom?: string;
    amountFrom?: string;
    amountTo?: string;
    paymentMethod?: string;
    ref?: string;
};