PaymentFlowManager

PaymentFlowManager is the top-level component that renders the complete TapRails payment experience. It handles all UI states, NFC operations, and API calls internally.

Import

import { PaymentFlowManager } from '@taprails/tap-to-pay';

Usage

{showFlow && (
  <PaymentFlowManager
    config={{
      type: 'merchant',         // or 'customer'
      onComplete: (data) => {}, // called on success
      onCancel: () => {},       // called when user cancels
      onError: (err) => {},     // called on error
    }}
    onMerchantCancel={() => setShowFlow(false)}
  />
)}

Props

PaymentFlowConfig

required

Configuration object that controls which flow to render and how to handle events.

() => void

Called when the merchant cancels the flow. Used to unmount the component. Required when config.type === 'merchant'.

() => void

Called when the customer cancels the flow. Required when config.type === 'customer'.

PaymentFlowConfig

interface PaymentFlowConfig {
  type: 'merchant' | 'customer';
  onComplete?: (data: MerchantFlowData | CustomerFlowData) => void;
  onCancel?: () => void;
  onError?: (error: Error) => void;
}

'merchant' | 'customer'

required

Determines which payment flow to render. 'merchant' shows the amount input + HCE waiting screen. 'customer' shows the tap instruction + processing screens.

(data) => void

Called when the payment flow completes successfully. Receives MerchantFlowData or CustomerFlowData depending on the flow type.

() => void

Called when the user explicitly cancels the flow.

(error: Error) => void

Called when an unrecoverable error occurs. The component remains mounted with an error screen — call your cancel handler from here to unmount if needed.

Callback Data Types

MerchantFlowData (onComplete for merchant)

interface MerchantFlowData {
  amount?: string;
  merchantId?: string;
  paymentRequest?: PaymentRequest;
  txHash?: string;
  error?: Error;
}

CustomerFlowData (onComplete for customer)

interface CustomerFlowData {
  paymentRequest?: PaymentRequest;
  customerWallet?: string;
  processedPayment?: ProcessPaymentResponse;
  error?: Error;
}

Flow State Machines

Merchant

idle → creating → waiting → success
                    ↓
                  error

Customer

idle → scanning → confirming → processing → success
          ↓                          ↓
        error                      error

Examples

<PaymentFlowManager
  config={{
    type: 'merchant',
    onComplete: ({ paymentRequest }) => {
      analytics.track('payment_received', {
        paymentId: paymentRequest?.paymentId,
      });
      setShowFlow(false);
    },
    onCancel: () => setShowFlow(false),
    onError: (err) => {
      Sentry.captureException(err);
      setShowFlow(false);
    },
  }}
  onMerchantCancel={() => setShowFlow(false)}
/>

<PaymentFlowManager
  config={{
    type: 'customer',
    onComplete: ({ processedPayment }) => {
      console.log('Paid! tx:', processedPayment?.transactionId);
      setShowFlow(false);
    },
    onCancel: () => setShowFlow(false),
    onError: (err) => console.error(err),
  }}
  onCustomerCancel={() => setShowFlow(false)}
/>

PaymentFlowManager renders as a full-screen overlay. Wrap it in a conditional render and toggle visibility via state, rather than using the visible prop pattern.

Get Started

Use Cases

React Native SDK

API

Webhooks

Coverage

PaymentFlowManager

Import

Usage

Props

PaymentFlowConfig

Callback Data Types

MerchantFlowData (onComplete for merchant)

CustomerFlowData (onComplete for customer)

Flow State Machines

Merchant

Customer

Examples

​Import

​Usage

​Props

​PaymentFlowConfig

​Callback Data Types

​MerchantFlowData (onComplete for merchant)

​CustomerFlowData (onComplete for customer)

​Flow State Machines

​Merchant

​Customer

​Examples

Import

Usage

Props

PaymentFlowConfig

Callback Data Types

MerchantFlowData (onComplete for merchant)

CustomerFlowData (onComplete for customer)

Flow State Machines

Merchant

Customer

Examples