npm package: @redpincompany/hosted-payment-sdk
Description: React Native SDK for Redpin Hosted Payment UI Service
Author: Redpin
Latest version: 1.0.5

# Redpin Hosted Payment SDK

A React Native SDK for integrating Redpin's hosted payment UI service into your mobile applications. This SDK provides a seamless way to embed the payment interface using WebView with full communication capabilities.

## Features

- 🚀 **Easy Integration**: Simple React Native component for quick setup
- 💬 **Bidirectional Communication**: Message passing between React Native and the hosted UI
- 🎨 **Theme Customization**: Override whitelabel theme with your app theme
- 🔒 **Type Safety**: Full TypeScript support with comprehensive type definitions
- 📱 **Cross Platform**: Works on both iOS and Android
- 🌐 **Automatic Origin Communication**: Sends platform, version, and device details
- 🧱 **Solid Defaults**: Sensible WebView defaults for security and compatibility

## Installation

```bash
npm install @redpincompany/hosted-payment-sdk
# or
yarn add @redpincompany/hosted-payment-sdk
```

### Peer Dependencies

```bash
npm install react-native-webview
# or
yarn add react-native-webview
```

## Quick Start

### Basic Usage

```tsx
import React from 'react';
import { View, StyleSheet } from 'react-native';
import { RedpinHostedPaymentView, PaymentSDKConfigType } from '@redpincompany/hosted-payment-sdk';

const App = () => {
  const config: PaymentSDKConfigType = {
    sessionUrl: 'https://hosted.redpin.app/hosted/your-session-id',
    origin: 'https://myapp.com',
  };

  const callbacks = {
    onError: (error) => {
      console.log('SDK error:', error);
    },
  };

  return (
    <View style={styles.container}>
      <RedpinHostedPaymentView
        config={config}
        callbacks={callbacks}
        style={styles.webview}
      />
    </View>
  );
};

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

export default App;
```

### Theming (optional)

```tsx
import { RedpinHostedPaymentView, PaymentSDKConfigType } from '@redpincompany/hosted-payment-sdk';

const config: PaymentSDKConfigType = {
  sessionUrl: 'https://hosted.redpin.app/hosted/your-session-id',
  origin: 'https://myapp.com',
  theme: {
    // Allowed fonts only: 'CircularXX' | 'Helvetica' | 'Roboto' | 'Arial' | 'sans-serif'
    fontFamily: 'CircularXX',
    baseFontSize: 16,
    primaryColor: '#007AFF',
    background: '#FFFFFF',
    textPrimary: '#000000',
    textDanger: '#FF3B30',
    buttonPrimary: { bg: '#007AFF', text: '#FFFFFF' },
    borderRadius: 8,
  },
};
```

> Note: Only the following font families are accepted by the SDK: `CircularXX`, `Helvetica`, `Roboto`, `Arial`, `sans-serif`.

### Custom Message Handling (advanced)

```tsx
import { RedpinHostedPaymentView, messageHandler, PaymentSDKConfigType } from '@redpincompany/hosted-payment-sdk';

const config: PaymentSDKConfigType = { sessionUrl: 'https://hosted.redpin.app/hosted/your-session-id' };

function Example() {
  return (
    <RedpinHostedPaymentView
      config={config}
      callbacks={{}}
      style={{ flex: 1 }}
      onMessage={(event) => {
        const parsed = messageHandler.parseIncomingMessage(event.nativeEvent.data);
        if (parsed?.type === 'CUSTOM_RESPONSE') {
          console.log('Custom response:', parsed.payload);
        }
      }}
    />
  );
}
```

## How it works

- The SDK embeds your hosted session URL in a WebView.
- On readiness, the hosted UI asks for theme via `READY_FOR_THEME`.
- The SDK responds by sending a `SET_THEME` message with your provided theme (if any) and also sends `SET_HOSTED_ORIGIN`.

Theme message shape sent by the SDK:

```ts
{
  type: 'SET_THEME',
  payload: {
    fontFamily?: 'CircularXX' | 'Helvetica' | 'Roboto' | 'Arial' | 'sans-serif';
    baseFontSize?: number;
    primaryColor?: string;
    background?: string;
    textPrimary?: string;
    textDanger?: string;
    buttonPrimary?: { bg?: string; text?: string };
    borderRadius?: number;
  }
}
```

Origin message shape sent by the SDK:

```ts
{
  type: 'SET_HOSTED_ORIGIN',
  origin: 'https://myapp.com',
  appInfo: { platform: 'react-native'; appVersion: string; deviceType: 'mobile' | 'tablet' | 'desktop'; timestamp: string }
}
```

## Configuration

```ts
interface PaymentSDKConfigType {
  sessionUrl: string; // Full session URL
  theme?: ThemeConfig; // Optional theming
  headers?: Record<string, string>; // Optional headers
  appVersion?: string; // For origin payload
  deviceType?: 'mobile' | 'tablet' | 'desktop'; // For origin payload
  origin?: string; // Custom origin to send to hosted UI
}

interface ThemeConfig {
  fontFamily?: 'CircularXX' | 'Helvetica' | 'Roboto' | 'Arial' | 'sans-serif';
  baseFontSize?: number;
  primaryColor?: string;
  background?: string;
  textPrimary?: string;
  textDanger?: string;
  buttonPrimary?: { bg: string; text: string };
  borderRadius?: number;
  // legacy fields (still accepted but mapped internally)
  backgroundColor?: string;
  textColor?: string;
  secondaryColor?: string;
  customCSS?: string;
}
```

## Callbacks

```ts
interface PaymentSDKCallbacks {
  onCloseApp?: () => void;
  onViewAllPayments?: () => void;
  onSessionExpired?: () => void;
  onError?: (error: { code: string; message: string; details?: any }) => void;
  onThemeUpdated?: (theme: ThemeConfig) => void;
}
```

## API Reference

### `RedpinHostedPaymentView` Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `config` | `PaymentSDKConfigType` | ✅ | SDK configuration |
| `callbacks` | `PaymentSDKCallbacks` | ❌ | Event callbacks |
| `style` | `ViewStyle` | ❌ | Container style |
| `onLoadStart` | `() => void` | ❌ | WebView load start |
| `onLoadEnd` | `() => void` | ❌ | WebView load end |
| `onError` | `(error: any) => void` | ❌ | WebView error |
| `showLoading` | `boolean` | ❌ | Show loading overlay (default: true) |
| `loadingComponent` | `React.ComponentType` | ❌ | Custom loading component |
| `debug` | `boolean` | ❌ | Enable debug logs (default: false) |
| `webViewStyle` | `ViewStyle` | ❌ | WebView style |
| `cacheEnabled` | `boolean` | ❌ | Enable cache (default: true) |
| `incognito` | `boolean` | ❌ | Incognito mode (default: false) |
| `thirdPartyCookiesEnabled` | `boolean` | ❌ | Third-party cookies (default: true) |
| `sharedCookiesEnabled` | `boolean` | ❌ | Shared cookies (default: true) |
| `mixedContentMode` | `'never' | 'always' | 'compatibility'` | ❌ | Android mixed content |

## Troubleshooting

- WebView not loading: verify `sessionUrl` and network access.
- Messages not received: ensure the WebView is fully loaded and message formats are correct.
- Theme not applying: check theme property names (e.g., `background`, `textPrimary`) and allowed fonts.

## License

MIT