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

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

Peer Dependencies

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

Quick Start

Basic Usage

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)

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)

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:

{
  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:

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

Configuration

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

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