> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.redpincompany.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.redpincompany.com/_mcp/server.

# Quickstart Setup

> Get started with Redpin B2B API integration - complete setup guide for API and Hosted UI integration

Get started with Redpin's B2B API integration quickly and easily. This guide provides complete setup instructions for both API integration and Hosted UI integration approaches.

> **Note**
>
> This quickstart guide provides production-ready examples that demonstrate the full B2B payment flow, from authentication to payment execution. Choose the integration approach that best fits your needs.

## Prerequisites

Before you begin, ensure you have:

* **API Credentials**: Your Redpin client ID and client secret
* **Customer ID**: Your assigned customer identifier
* **Development Environment**: Choose your preferred platform below

## Integration Options

Redpin offers two main integration approaches:

#### API Integration

**For backend applications and custom integrations**

Direct API access for complete control over the payment flow:

* Full API control and customization
* Backend-only integration
* Multiple language support (Java, Python)
* Production-ready examples with error handling

#### Hosted UI Integration

**Reference implementations for third-party applications**

Complete example applications demonstrating hosted payment flow integration:

* React.js web application reference
* React Native mobile app reference
* Embedded Redpin payment interface
* Real-world integration patterns and best practices

## API Integration

Complete backend integration examples in Java and Python that demonstrate the full B2B payment flow.

For the detailed step-by-step payment lifecycle, see the [API integration workflow](/api-guide/partners/integration-guidelines#api-integration-workflow).

### Choose Your Language

#### Java

### Java Integration

#### Prerequisites

* Java 11 or higher
* Maven 3.6 or higher

#### Step 1: Clone and Setup

```bash
# Clone the quickstart repository
git clone https://gitlab.com/Redpin.Opensource/quickstart.git
cd quickstart/api-integration/java

# Build the project
mvn clean install
```

#### Step 2: Configure Environment

```bash
# Copy the configuration template
cp src/main/resources/application.properties.example src/main/resources/application.properties

# Edit with your actual credentials
```

#### Step 3: Run the Integration

```bash
mvn exec:java -Dexec.mainClass="com.b2b.integration.B2BIntegrationApplication"
```

#### Python

### Python Integration

#### Prerequisites

* Python 3.8 or higher
* pip package manager

#### Step 1: Clone and Setup

```bash
# Clone the quickstart repository
git clone https://gitlab.com/Redpin.Opensource/quickstart.git
cd quickstart/api-integration/python

# Install dependencies
pip install -r requirements.txt
```

#### Step 2: Configure Environment

```bash
# Copy the configuration template
cp config.example.py config.py

# Edit with your actual credentials
```

#### Step 3: Run the Integration

**Complete Flow:**

```bash
python main.py
```

**Individual Components:**

```bash
# Authentication
python auth_manager.py

# Webhook management
python webhook_manager.py

# Customer management
python customer_manager.py

# Recipient management
python recipient_manager.py

# Quote management
python quote_manager.py

# Payment management
python payment_manager.py
```

### API Integration Flow

The complete integration follows this sequence:

```mermaid
flowchart LR
    A[Authentication] --> B[Webhook Setup]
    B --> C[Customer Creation]
    C --> D[Recipient Creation]
    D --> E[Quote Creation]
    E --> F[Payment Execution]
```

1. **🔐 Authentication** - Create access token using client credentials
2. **🔔 Webhook Subscription** - Set up real-time payment status notifications
3. **👤 Customer Creation** - Register third-party customer information
4. **👥 Recipient Creation** - Add payment recipient details
5. **💱 Quote Creation** - Get exchange rate quotes
6. **💳 Payment Creation** - Execute the international payment

> **Note**
>
> The API integration examples include comprehensive error handling, logging, validation, and testing to ensure production readiness.

## Hosted UI Integration

Reference implementations demonstrating how to integrate Redpin's hosted payment flow into third-party applications. These example apps show the complete integration flow, from user interaction to payment completion.

### Choose Your Platform

#### React.js

### React.js Reference Application

#### Prerequisites

* Node.js (v18 or higher)
* npm or yarn
* Modern web browser

> **Note**
>
> This is a **reference implementation** that demonstrates how to integrate Redpin's hosted payment flow into a React.js application. Use this as a guide for implementing similar functionality in your own applications.

#### Step 1: Clone and Setup

```bash
# Clone the quickstart repository
git clone https://gitlab.com/Redpin.Opensource/quickstart.git
cd quickstart/hosted-ui-integration/ReactJs

# Install dependencies
npm install
```

#### Step 2: Configure Environment

```bash
# Copy environment template
cp .env.example .env

# Edit with your actual credentials
```

#### Step 3: Start the Backend Server

```bash
# Start the API server (required for Redpin integration)
npm run server
# or
node server.js
```

The server will start on `http://localhost:8080`

#### Step 4: Start the React App

```bash
# In a new terminal, start the React development server
npm start
# or
npm run dev
```

The app will open at `http://localhost:3000`

#### Available Scripts

| Command          | Description                     |
| ---------------- | ------------------------------- |
| `npm start`      | Start React development server  |
| `npm run dev`    | Start both server and React app |
| `npm run server` | Start API server only           |
| `npm run build`  | Build for production            |
| `npm run lint`   | Run ESLint                      |

#### React Native

### React Native Reference Application

#### Prerequisites

* Node.js (v18 or higher)
* npm or yarn
* React Native development environment
* **For Android:** Android Studio, Android SDK, Android emulator or physical device
* **For iOS (macOS only):** Xcode, iOS Simulator or physical device
* **For testing:** Expo Go app installed on your device

> **Note**
>
> This is a **reference implementation** that demonstrates how to integrate Redpin's hosted payment flow into a React Native mobile application. Use this as a guide for implementing similar functionality in your own mobile apps.
>
> **Note:** The app uses Expo framework for easier development and testing. You can run it on physical devices using Expo Go app or on emulators/simulators.

#### Step 1: Clone and Setup

```bash
# Clone the quickstart repository
git clone https://gitlab.com/Redpin.Opensource/quickstart.git
cd quickstart/hosted-ui-integration/ReactNative

# Install dependencies
npm install
```

#### Step 2: Configure Environment

```bash
# Copy environment template
cp env.example .env

# Edit with your actual credentials
```

#### Step 3: Start the Backend Server

```bash
# Start the API server (required for Redpin integration)
npm run server
# or
node server.mjs
```

The server will start on `http://localhost:8082`

#### Step 4: Setup Development Environment

**For Android Development:**

1. **Install Android Studio:**
   * Download and install [Android Studio](https://developer.android.com/studio)
   * Install Android SDK and build tools
   * Create an Android Virtual Device (AVD)
   * **Java Requirements**: Android Studio requires Java 11 or higher (OpenJDK 17+ recommended)

2. **Configure Android SDK Environment Variables:**

   **For macOS/Linux:**

   ```bash
   # Add to your ~/.zshrc or ~/.bash_profile
   export ANDROID_HOME=$HOME/Library/Android/sdk
   export PATH=$PATH:$ANDROID_HOME/emulator
   export PATH=$PATH:$ANDROID_HOME/platform-tools
   export PATH=$PATH:$ANDROID_HOME/tools
   export PATH=$PATH:$ANDROID_HOME/tools/bin
   ```

   **For Windows:**

   ```cmd
   # Add these environment variables in System Properties > Environment Variables
   ANDROID_HOME=C:\Users\%USERNAME%\AppData\Local\Android\Sdk
   PATH=%PATH%;%ANDROID_HOME%\emulator
   PATH=%PATH%;%ANDROID_HOME%\platform-tools
   PATH=%PATH%;%ANDROID_HOME%\tools
   PATH=%PATH%;%ANDROID_HOME%\tools\bin
   ```

   **Verify Configuration:**

   ```bash
   # Restart your terminal and verify the setup
   adb --version
   emulator --version
   ```

3. **Setup Android Emulator:**
   ```bash
   # Open Android Studio and go to AVD Manager
   # Create a new virtual device (recommended: Pixel 6, API 33)
   # Start the emulator from Android Studio or command line:
   emulator -avd Pixel_6_API_33
   ```

4. **Install Expo Go App:**
   * Download [Expo Go](https://expo.dev/client) from Google Play Store
   * This app allows you to run the reference application on your device

**For iOS Development (macOS only):**

1. **Install Xcode:**
   * Download and install [Xcode](https://developer.apple.com/xcode/) from Mac App Store
   * Install iOS Simulator and development tools

2. **Setup iOS Simulator:**
   ```bash
   # Open Xcode and go to Xcode > Preferences > Components
   # Download and install iOS Simulator (recommended: iPhone 14, iOS 16)
   # Start simulator from Xcode or command line:
   open -a Simulator
   ```

3. **Install Expo Go App:**
   * Download [Expo Go](https://expo.dev/client) from App Store
   * This app allows you to run the reference application on your device

#### Step 5: Start the React Native App

**For Android:**

```bash
# Start the React Native development server
npm run android
# or
npx expo run:android
```

**For iOS (macOS only):**

```bash
# Start the React Native development server
npm run ios
# or
npx expo run:ios
```

**Alternative: Using Expo Go (Recommended for testing):**

```bash
# Start the Expo development server
npx expo start

# Scan the QR code with Expo Go app on your device
# Or press 'a' for Android emulator, 'i' for iOS simulator
```

#### Available Scripts

| Command           | Description                      |
| ----------------- | -------------------------------- |
| `npm run android` | Start Android development server |
| `npm run ios`     | Start iOS development server     |
| `npm run server`  | Start API server only            |
| `npm run build`   | Build for production             |

#### React Native SDK

### React Native SDK Integration

The Redpin Hosted Payment SDK provides a native React Native component for seamless payment integration with enhanced features and automatic configuration.

> **Note**
>
> The **Redpin Hosted Payment SDK** is a React Native package that provides a native WebView component specifically designed for Redpin's hosted payment flows. It handles session management, theme customization, and provides enhanced callbacks for better user experience.

#### Prerequisites

* Node.js (v18 or higher)
* npm or yarn
* React Native development environment
* **For Android:** Android Studio, Android SDK, Android emulator or physical device
* **For iOS (macOS only):** Xcode, iOS Simulator or physical device

#### Step 1: Install the SDK

[View `@redpincompany/hosted-payment-sdk` 2.0.0 on npm](https://www.npmjs.com/package/@redpincompany/hosted-payment-sdk/v/2.0.0).

```bash
# Install the Redpin Hosted Payment SDK
npm install @redpincompany/hosted-payment-sdk

# Install peer dependencies
npm install react-native-webview

# For iOS, you may need to run pod install
cd ios && pod install && cd ..
```

> **Note**
>
> **Peer Dependencies**: The SDK requires `react-native-webview` as a peer dependency. Make sure to install it alongside the SDK for proper functionality.

#### Step 2: Basic Integration

```tsx
import React, { useState } from 'react';
import { View, Text, TouchableOpacity, Alert } from 'react-native';
import {
  RedpinHostedPaymentView,
  PaymentSDKConfigType,
  PaymentErrorType,
} from '@redpincompany/hosted-payment-sdk';

const PaymentScreen = () => {
  const [showPayment, setShowPayment] = useState(false);

  // SDK Configuration
  const config: PaymentSDKConfigType = {
    sessionUrl: 'https://hosted.redpin.app/hosted/your-session-id',
    origin: 'https://myapp.com',
    appVersion: '1.0.0',
    deviceType: 'mobile',
    analyticsConsent: false, // Set from your CMP; default false
    theme: {
      fontFamily: 'CircularXX', // Allowed: 'CircularXX' | 'Helvetica' | 'Roboto' | 'Arial' | 'sans-serif'
      baseFontSize: 14,
      primaryColor: '#1E40AF',
      background: '#F8FAFC',
      textPrimary: '#1F2937',
      buttonPrimary: {
        bg: '#1E40AF',
        text: '#FFFFFF'
      },
      borderRadius: 6
    },
    headers: {
      'X-App-Version': '1.0.0',
      'X-Platform': 'react-native',
    },
  };

  const callbacks = {
    onCloseApp: () => {
      Alert.alert('Close App', 'Payment interface requested to close');
      setShowPayment(false);
    },
    onPaymentFlowExited: () => {
      // User left payment tracking from the hosted thank-you page.
      Alert.alert('Payment flow exited', 'Leave the hosted flow, for example by navigating to payment history');
    },
    onSessionExpired: () => {
      Alert.alert('Session Expired', 'Please refresh and try again');
    },
    onError: (error: PaymentErrorType) => {
      Alert.alert('Error', `${error.code}: ${error.message}`);
    },
  };

  return (
    <View style={{ flex: 1 }}>
      <TouchableOpacity onPress={() => setShowPayment(true)}>
        <Text>Start Payment</Text>
      </TouchableOpacity>
      
      {showPayment && (
        <RedpinHostedPaymentView
          config={config}
          callbacks={callbacks}
          style={{ flex: 1 }}
          debug={true}
        />
      )}
    </View>
  );
};
```

#### Step 3: SDK Features

The Redpin Hosted Payment SDK provides:

**Core Features:**

* **Native WebView Integration** - Optimized WebView component for payment flows
* **Automatic Session Management** - Handles session URLs and expiration
* **Theme Customization** - Customize payment interface appearance
* **Enhanced Callbacks** - Rich callback system for user interactions

**Advanced Features:**

* **Automatic Origin Communication** - Sends app information to hosted interface
* **Analytics consent** - Sends `analyticsConsent` from your CMP to the hosted session
* **Custom Headers Support** - Add custom headers for API communication
* **Debug Logging** - Comprehensive logging for development
* **Error Handling** - Detailed error types and messages
* **Session Expiration Handling** - Automatic session renewal

**Configuration Options:**

```tsx
const config: PaymentSDKConfigType = {
  sessionUrl: 'https://hosted.redpin.app/hosted/session-id',
  origin: 'https://myapp.com',           // Custom origin
  appVersion: '1.0.0',                  // App version
  deviceType: 'mobile',                 // Device type: 'mobile' | 'tablet' | 'desktop'
  analyticsConsent: false,              // Optional. Whether the user granted analytics consent. Default: false
  theme: {                              // Theme customization
    fontFamily: 'CircularXX',           // Allowed: 'CircularXX' | 'Helvetica' | 'Roboto' | 'Arial' | 'sans-serif'
    baseFontSize: 16,
    primaryColor: '#007AFF',
    background: '#FFFFFF',
    textPrimary: '#000000',
    textDanger: '#FF3B30',
    buttonPrimary: { bg: '#007AFF', text: '#FFFFFF' },
    borderRadius: 8,
  },
  headers: {                           // Custom headers
    'X-App-Version': '1.0.0',
    'X-Platform': 'react-native',
  },
};
```

**Analytics consent:** `analyticsConsent` is optional and defaults to `false`. Set it from your CMP decision. If you omit it or pass `false`, product analytics and session diagnostics stay off in the hosted session.

**Theme Restrictions:**

* **Font Family**: Only the following fonts are accepted: `CircularXX`, `Helvetica`, `Roboto`, `Arial`, `sans-serif`
* **Color Format**: Use hex color codes (e.g., `#007AFF`)
* **Font Size**: Use numeric values for `baseFontSize`
* **Button Colors**: Specify both background (`bg`) and text (`text`) colors

**Available Callbacks:**

* `onCloseApp` - When user requests to close the app
* `onPaymentFlowExited` - `() => void`. Called when the hosted UI posts `REDPIN_PAYMENT_TRACKING_EXITED`, which is when the user exits payment tracking from the thank-you page. The SDK does not pass a payload. Use it to leave the hosted flow.
* `onSessionExpired` - When payment session expires
* `onError` - When errors occur during payment

Added in [`@redpincompany/hosted-payment-sdk` 2.0.0](https://www.npmjs.com/package/@redpincompany/hosted-payment-sdk/v/2.0.0). `onPaymentFlowExited` replaces `onViewAllPayments`. Apps still on `onViewAllPayments` are not called. A message with type `VIEW_ALL_PAYMENTS` is ignored.

#### Step 4: Development Setup

**For Android:**

```bash
# Start the React Native development server
npm run android
# or
npx react-native run-android
```

**For iOS (macOS only):**

```bash
# Start the React Native development server
npm run ios
# or
npx react-native run-ios
```

#### Step 5: Testing

The SDK includes comprehensive testing features:

```tsx
// Enable debug mode for development
<RedpinHostedPaymentView
  config={config}
  callbacks={callbacks}
  debug={true}  // Enable debug logging
  style={{ flex: 1 }}
/>
```

**Debug Features:**

* Console logging for all SDK events
* Error tracking and reporting
* Session state monitoring
* Network request logging

#### 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

**Common Issues:**

* **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
* **Font not working**: Only use allowed font families: `CircularXX`, `Helvetica`, `Roboto`, `Arial`, `sans-serif`
* **Colors not applying**: Use hex color codes (e.g., `#007AFF`) for all color properties

#### Available Scripts

| Command           | Description                      |
| ----------------- | -------------------------------- |
| `npm run android` | Start Android development server |
| `npm run ios`     | Start iOS development server     |
| `npm run build`   | Build for production             |
| `npm run test`    | Run SDK tests                    |

### Key Integration Features Demonstrated

These reference applications demonstrate essential integration patterns:

* **Payment Flow Integration** - How to embed Redpin payment options in your app
* **API Call Flow** - Complete flow from user click to payment completion
* **Session Management** - Handling payment sessions and user state
* **Compliance Checks** - Alert handling for incomplete compliance requirements
* **Error Handling** - Managing payment failures and edge cases
* **Success Flow** - Seamless user experience after successful payments
* **WebView Integration** - Embedding hosted payment interface
* **Theme Customization** - How to customize hosted UI with basic theme parameters

> **Note**
>
> The reference apps include examples of theme customization, showing how to modify the hosted payment interface appearance using basic theme parameters to match your application's branding.

### Hosted UI Integration Flow

The hosted UI integration follows this user journey:

```mermaid
flowchart LR
    A[User Login & Select Property] --> B[Choose Payment Amount]
    B --> C[Select Redpin Payment]
    C --> D[Check for Existing Session]
    
    style A fill:#e1f5fe,stroke:#01579b,stroke-width:3px
    style B fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style C fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style D fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
```

**Payment Process:**

```mermaid
flowchart LR
    D[Check for Existing Session] --> E{Session Exists?}
    E -->|Yes| F[Open Existing Session URL]
    E -->|No| G[Create New Session]
    G --> H[Open New Session URL]
    F --> I[Complete Payment Flow]
    H --> I
    I --> J[Payment Success]
    
    style D fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
    style E fill:#fff3e0,stroke:#e65100,stroke-width:3px
    style F fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    style G fill:#ffebee,stroke:#c62828,stroke-width:2px
    style H fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    style I fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style J fill:#e8f5e8,stroke:#1b5e20,stroke-width:3px
```

**What Happens Behind the Scenes:**

The reference apps automatically handle:

* **Customer Management** - Creating or updating customer information
* **Compliance Checks** - Ensuring all required information is complete
* **Session Optimization** - Reusing existing sessions for faster payments
* **Payment Processing** - Secure payment flow through hosted interface
* **Status Updates** - Real-time payment status notifications
* **Theme Customization** - Matching the payment interface to your app's branding

> **Note**
>
> These reference applications include a backend server (server.js/server.mjs) that demonstrates how to proxy API calls and handle authentication securely. Study the server implementation to understand the required backend integration patterns. The apps also showcase theme customization capabilities for the hosted payment interface.

## What You Can Expect

### Backend Integration Examples

* **Authentication Flow** - Secure token-based authentication
* **Customer Management** - Create and manage third-party customers
* **Recipient Management** - Add and manage payment recipients
* **Quote Management** - Get real-time exchange rate quotes
* **Payment Processing** - Execute international payments
* **Webhook Handling** - Real-time payment status updates

### Reference Application Features

* **Payment Flow Integration** - Complete example of embedding Redpin payments
* **API Call Patterns** - Demonstrates proper API calling sequence
* **Session Management** - Shows how to handle payment sessions
* **Compliance Handling** - Examples of compliance check alerts and flows
* **Error Scenarios** - Comprehensive error handling examples
* **Success Flows** - Complete user journey after successful payment
* **WebView Integration** - How to embed hosted payment interface
* [**Theme Customization**](/api-guide/partners/integration-guidelines#step-5-custom-theme-integration-optional) - Examples of customizing hosted UI themes with basic parameters
* [**Analytics consent (embedded hosts)**](/api-guide/partners/integration-guidelines#step-6-analytics-consent-integration-embedded-hosts) - Forward host CMP analytics consent to the hosted session via `SET_ANALYTICS_CONSENT`
* **Real-time Status** - Live payment status updates and notifications

## Need Help?

If you encounter any issues during setup:

1. **Study the Reference Code** - Review the React.js and React Native implementations
2. **Check API Documentation** - Refer to the complete API reference
3. **Verify Configuration** - Ensure all environment variables are set correctly
4. **Test Connectivity** - Verify API endpoints are accessible
5. **Review Integration Patterns** - Study how the reference apps handle payment flows
6. **Contact Support** - Reach out to our support team for assistance

> **Note**
>
> Make sure to use sandbox credentials for testing and development. Production credentials should only be used in production environments.