Datman Checkout SDK for React Native

A sleek, privacy-first iOS checkout experience for React Native.
Minimal JS surface. Beautiful SwiftUI sheets. All payment logic sealed inside a native .xcframework.

Why this SDK

• Drop-in UI: polished card entry flow via native SwiftUI sheets.
• Tiny API surface: setup, configure, open -- just three functions.
• Sealed native core: network + validation + UI + 3-D Secure live in a vendored .xcframework -- your app only sees a slim bridge.
• End-to-end encryption: card data is encrypted with RSA + AES-GCM before leaving the device.
• Themeable: brand color + logo.
• Type-safe: first-class TypeScript types.

iOS supported today. Android can be added with a matching Kotlin .aar + RN bridge.

Install

# in your React Native app
npm i react-native-datman-checkout-sdk
# or
yarn add react-native-datman-checkout-sdk

# iOS pods
npx pod-install

If autolinking is restricted in your workspace, add this to your ios/Podfile (inside your app target):

pod 'RNDatmanCheckout', :path => '../node_modules/react-native-datman-checkout-sdk'

Then pod install again.

Make sure your iOS app target has Other Linker Flags: $(inherited) and -ObjC.

Quick start

import { Alert, Button, SafeAreaView } from 'react-native';
import DatmanCheckout from 'react-native-datman-checkout-sdk';

// 1. Setup (once, on app boot or before first payment)
await DatmanCheckout.setup({
  baseUrl: 'https://ws5-payments.datmanpay.com',
  apiKey: 'YOUR_API_KEY',
  brandColorHex: '#0A84FF',
  logoUrl: 'https://example.com/logo.png',
  publicKey: '-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----',
});

// 2. Create session on your backend, then configure SDK
const sessionId = await yourBackend.createSession({ amount, orderId, ... });
await DatmanCheckout.configure(sessionId);

// 3. Open the native checkout sheet
const result = await DatmanCheckout.open();

if (result.status === 'success') {
  Alert.alert('Payment successful!', `Sale ID: ${result.saleId}`);
} else if (result.status === 'failed') {
  Alert.alert('Payment failed', result.message);
} else if (result.status === 'cancelled') {
  Alert.alert('Cancelled', result.message);
}

API

setup(options?) => Promise<boolean>

Optional. Override defaults inside the native SDK. Call once before the first payment.

type SetupOptions = {
  baseUrl?: string;         // Payment API base URL
  apiKey?: string;          // API key for /sale-handler authentication
  brandColorHex?: string;   // Brand color in hex (e.g., "#0A84FF")
  logoUrl?: string;         // URL to brand logo
  publicKey?: string;       // RSA public key (PEM) for card data encryption
};

configure(sessionId) => Promise<boolean>

Set the session ID returned by your backend's /create-session endpoint. Must be called before open().

await DatmanCheckout.configure('sess_abc123');

open() => Promise<OpenResult>

Opens the native checkout sheet. The SDK internally calls /get-session to fetch session metadata, presents the card form, handles validation, encryption, submission, and 3-D Secure if required.

Returns a Promise that resolves when the user completes or cancels the flow.

type OpenResult = {
  status: 'success' | 'failed' | 'cancelled';
  saleId?: string;
  reference?: string;
  message?: string;
  raw?: any;       // full gateway JSON (for diagnostics)
};

Payment flow

Your App                     SDK (Native)                  Your Backend
────────                     ────────────                  ────────────
                                                           
POST /create-session ──────────────────────────────────────►
◄──────────────────────────────────────────── { sessionId } 
                                                           
configure(sessionId) ──────► stores session ID             
                                                           
open() ────────────────────► GET /get-session ─────────────►
                             ◄──────────── session metadata 
                             Show card form                
                             User enters card              
                             Encrypt card (RSA+AES-GCM)    
                             POST /sale-handler ───────────►
                             ◄────────── response           
                             If 3DSv2 → WebView challenge  
                             ◄──── result                  
◄──── { status, saleId }                                   

UI & theming

• Brand color tints primary buttons and toggles.
• Logo URL appears in the payment header (square recommended).
• Light/Dark mode follows the host app.

All screens are powered by SwiftUI and presented as a sheet for a native feel.

Security

• Card data (PAN, CVV, expiry) is handled exclusively within native code.
• When a publicKey is provided via setup(), card data is encrypted using hybrid RSA-OAEP + AES-256-GCM before transmission.
• Ephemeral URLSession is used (no cookies or cache).
• No sensitive fields are logged, stored, or exposed to the JS layer.
• 3-D Secure v2 is supported natively via WebView.

What ships in this package?

• ios/RNPayCore.xcframework -- the sealed native core (UI + network + validation + encryption + 3DS).
• Tiny RN bridge -- RNDatmanCheckout native module (Swift + Obj-C shim).
• TypeScript surface -- just three functions with full type definitions.

Requirements

• iOS 15.0+
• React Native >= 0.71
• CocoaPods
• Bare workflow (or EAS with a config plugin; managed workflow isn't supported out of the box)

Troubleshooting

"Native module not found"

• Run npx pod-install.
• Open the .xcworkspace (not the .xcodeproj).
• Check Podfile.lock contains RNDatmanCheckout.
• Ensure your app target has Other Linker Flags: -ObjC.

Simulator crash: "calling into SwiftUI on a non-main thread"

• Update to the latest SDK. UI presentation is dispatched to the main thread in the bridge and marked @MainActor in the native core.

Linker / module header warnings

• Harmless for pure Swift frameworks; the podspec already enables DEFINES_MODULE.
• Built with BUILD_LIBRARY_FOR_DISTRIBUTION=YES for ABI stability.

Roadmap

• Android parity (native Kotlin UI + .aar)
• Config plugin for Expo/EAS
• Saved cards / tokenization flow
• Additional themes & localization hooks

License

MIT (c) Datman