Skip to main content
This guide is specifically for the React Native SDK. Building with another framework? See Supported Frameworks.

​
1. Initialize the SDK

Call ContactlessCryptoSDK.initialize() once, before rendering any components that use the SDK. Your app entry point is ideal. 
import { ContactlessCryptoSDK, PaymentMode } from '@taprails/tap-to-pay';

ContactlessCryptoSDK.initialize({
  apiKey: 'pk_live_your_api_key',
  apiUrl: 'https://api.yourbackend.com',
  environment: 'production',
  merchantId: 'merchant_123',
  mode: PaymentMode.POOL,
  pool: {
    customerId: 'customer_456',
  },
});
Not sure which mode to use? See Payment Modes.

​
2. Wrap Your App

Wrap your root component with TapRailsThemeProvider. In SESSION_KEY mode this also handles automatic session key setup UI.
App.tsx
import { TapRailsThemeProvider } from '@taprails/tap-to-pay';

export default function App() {
  return (
    <TapRailsThemeProvider>
      <YourNavigation />
    </TapRailsThemeProvider>
  );
}

​
3. Accept a Payment (Merchant)

Add a button that opens the TapRails payment flow:
MerchantScreen.tsx
import { PaymentFlowManager } from '@taprails/tap-to-pay';
import { useState } from 'react';
import { Button } from 'react-native';

export function MerchantScreen() {
  const [showFlow, setShowFlow] = useState(false);

  return (
    <>
      <Button title="Accept Payment" onPress={() => setShowFlow(true)} />

      {showFlow && (
        <PaymentFlowManager
          config={{
            type: 'merchant',
            onComplete: (data) => {
              console.log('Payment received!', data);
              setShowFlow(false);
            },
            onCancel: () => setShowFlow(false),
            onError: (err) => console.error(err),
          }}
          onMerchantCancel={() => setShowFlow(false)}
        />
      )}
    </>
  );
}
What the user sees:
  1. Amount input screen → enter the charge amount
  2. NFC waiting screen → animated icon, countdown timer
  3. Success screen → transaction receipt

​
4. Make a Payment (Customer)

CustomerScreen.tsx
import { PaymentFlowManager } from '@taprails/tap-to-pay';
import { useState } from 'react';
import { Button } from 'react-native';

export function CustomerScreen() {
  const [showFlow, setShowFlow] = useState(false);

  return (
    <>
      <Button title="Pay Now" onPress={() => setShowFlow(true)} />

      {showFlow && (
        <PaymentFlowManager
          config={{
            type: 'customer',
            onComplete: (data) => {
              console.log('Payment sent!', data);
              setShowFlow(false);
            },
            onCancel: () => setShowFlow(false),
            onError: (err) => console.error(err),
          }}
          onCustomerCancel={() => setShowFlow(false)}
        />
      )}
    </>
  );
}
What the user sees:
  1. Tap instruction screen → “Hold your phone near the payment terminal”
  2. Processing screen → step-by-step progress
  3. Success screen → receipt with transaction details

​
You’re Done!

The SDK handles NFC communication, invoice signing, signature verification, payment API calls, and all UI states automatically.

​
Next Steps

Android Setup

Required gradle config, manifest permissions, and HCE service setup.

iOS Setup

Pod install and Info.plist NFC permission.

Payment Modes

Deep-dive on POOL vs SESSION_KEY.

Error Handling

Handle every NFC and API error gracefully.