Quickstart (React Native)

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',
  aid: 'YOUR_UNIQUE_AID',
  mode: PaymentMode.POOL,
  pool: {
    customerId: 'customer_456',
  },
});

import { ContactlessCryptoSDK, PaymentMode } from '@taprails/tap-to-pay';

ContactlessCryptoSDK.initialize({
  apiKey: 'pk_live_your_api_key',
  apiUrl: 'https://api.yourbackend.com',
  environment: 'production',
  aid: 'YOUR_UNIQUE_AID',
  mode: PaymentMode.SESSION_KEY,
  sessionKey: {
    walletAddress: '0x1234...abcd',
    defaultDailyLimit: '100.00',
    autoRenew: true,
    onSignTransaction: async (tx) => {
      // Hand off to your wallet provider
      return await myWallet.signTransaction(tx);
    },
  },
});

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:

Amount input screen → enter the charge amount
NFC waiting screen → animated icon, countdown timer
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:

Tap instruction screen → “Hold your phone near the payment terminal”
Processing screen → step-by-step progress
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.

Get Started

Use Cases

React Native SDK

API

Webhooks

Coverage

Quickstart (React Native)

1. Initialize the SDK

2. Wrap Your App

3. Accept a Payment (Merchant)

4. Make a Payment (Customer)

You’re Done!

Next Steps

Android Setup

iOS Setup

Payment Modes

Error Handling

​1. Initialize the SDK

​2. Wrap Your App

​3. Accept a Payment (Merchant)

​4. Make a Payment (Customer)

​You’re Done!

​Next Steps

Android Setup

iOS Setup

Payment Modes

Error Handling

1. Initialize the SDK

2. Wrap Your App

3. Accept a Payment (Merchant)

4. Make a Payment (Customer)

You’re Done!

Next Steps