React Native & Mobile Integration

The SimpleCheckout SDK is primarily designed for web environments (DOM). For React Native and other mobile frameworks, we provide a Hosted Connection Flow.

This approach avoids direct DOM manipulation issues by loading the secure form inside a WebView.

Example Repository: For a complete working example, see github.com/Fewsats/simplecheckout-react-native

How it Works

Instead of installing the SDK directly in your React Native app, you use a WebView component to load our specialized hosted page.

1. You Load URL: Point your WebView to https://connect.simplecheckout.ai with your keys.
2. User Connects: The user enters their credentials in the secure WebView.
3. We Message You: Upon success, the page sends a postMessage event back to your app with the account details.

React Native Implementation

First, install react-native-webview:

npm install react-native-webview

Then, implement the connection screen:

import React from 'react';
import { StyleSheet, View, ActivityIndicator } from 'react-native';
import { WebView } from 'react-native-webview';

const ConnectAccountScreen = ({ navigation }) => {
  // 1. Construct the URL with your configuration
  const publishableKey = 'pk_sandbox_...';
  const customerId = '...'; 
  const loginSourceId = '...';
  
  const uri = `https://connect.simplecheckout.ai?publishable_key=${publishableKey}&customer_id=${customerId}&login_source_id=${loginSourceId}`;

  // 2. Handle messages from the WebView
  const handleMessage = (event) => {
    try {
      const data = JSON.parse(event.nativeEvent.data);

      switch (data.type) {
        case 'SUCCESS':
          console.log('Account Connected:', data.payload);
          // data.payload contains { id: 'acct_...', customer_id: '...', ... }
          navigation.goBack(); // Close the modal
          break;

        case 'ERROR':
          const { code, message } = data.payload;
          if (code === 'INVALID_CREDENTIALS') {
            // Wrong password - show error, let user retry
          } else if (code === 'CONNECTION_FAILED') {
            // Network/server issue - show "try again later"
          }
          // CONFIGURATION_ERROR means integration bug - log for debugging
          console.error('Connection Error:', code, message);
          break;
          
        default:
          break;
      }
    } catch (e) {
      console.warn('Invalid message format', event.nativeEvent.data);
    }
  };

  return (
    <View style={styles.container}>
      <WebView
        source={{ uri }}
        onMessage={handleMessage}
        startInLoadingState={true}
        renderLoading={() => <ActivityIndicator size="large" />}
        style={styles.webview}
      />
    </View>
  );
};

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

export default ConnectAccountScreen;

URL Parameters

The following parameters can be passed as query strings in the URL:

• publishable_key (required): Your Publishable Key (pk_...)
• customer_id (required): The ID of the customer you are connecting
• login_source_id (required): The ID of the login source

Message Protocol

The WebView will send JSON strings with the following structure:

Success Message

{
  "type": "SUCCESS",
  "payload": {
    "id": "019a5a2b...",
    "customer_id": "...",
    "login_source_id": "...",
    "login_status": "LOGGED_IN"
  }
}

Error Message

{
  "type": "ERROR",
  "payload": {
    "code": "INVALID_CREDENTIALS",
    "message": "Wrong email or password"
  }
}

Error Codes

Code	Description	Action
CONFIGURATION_ERROR	Missing URL parameters or initialization failed	Fix integration
INVALID_CREDENTIALS	Wrong email or password	Let user retry
CONNECTION_FAILED	Server error, timeout, or network issue	Show "try again later"

TypeScript Types

If you're using TypeScript, here are the type definitions for the message protocol:

type MessageType = 'SUCCESS' | 'ERROR';

interface SuccessPayload {
  id: string;
  customer_id: string;
  login_source_id: string;
  login_status: string;
}

interface ErrorPayload {
  code: 'CONFIGURATION_ERROR' | 'INVALID_CREDENTIALS' | 'CONNECTION_FAILED';
  message: string;
}

interface BridgeMessage {
  type: MessageType;
  payload: SuccessPayload | ErrorPayload;
}

Example usage with typed handler:

import { WebViewMessageEvent } from 'react-native-webview';

const handleMessage = (event: WebViewMessageEvent) => {
  const data: BridgeMessage = JSON.parse(event.nativeEvent.data);

  if (data.type === 'SUCCESS') {
    const { id, login_status } = data.payload as SuccessPayload;
    // Handle success
  } else if (data.type === 'ERROR') {
    const { code, message } = data.payload as ErrorPayload;
    // Handle error based on code
  }
};

Universal Mobile Support

This hosted flow is not limited to React Native. The bridge automatically detects the environment and sends messages to:

• iOS Native (WKWebView): window.webkit.messageHandlers.simpleCheckout.postMessage(...)
• Android Native: window.SimpleCheckoutAndroid.postMessage(...)
• Flutter: Supports JavascriptChannel
• Web: Supports window.parent.postMessage (iFrames)