useNFCCustomer

useNFCCustomer manages the customer side of the payment flow: scanning an NFC tag from a merchant device and processing the payment via the TapRails backend.

Import

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

Usage

const {
  scanPaymentRequest,
  processPaymentRequest,
  isReading,
  isProcessing,
  paymentRequest,
  processedPayment,
  error,
  clearPayment,
  clearError,
} = useNFCCustomer();

Return Value

() => Promise<PaymentRequest | null>

Activates the NFC reader and waits for a merchant’s tag. Validates the ECDSA signature, expiry, and timestamp window before returning. Returns null on failure (check error).

(paymentId, txHash, customerWallet?) => Promise<ProcessPaymentResponse | null>

Submits the scanned payment to the TapRails backend for execution. Returns null on failure.

boolean

true while the NFC reader is open and waiting for a tag.

boolean

Alias for isReading.

boolean

true while the backend payment request is in-flight.

PaymentRequest | null

The payment request read from the NFC tag, or null before a scan.

ProcessPaymentResponse | null

The result of processing the payment, or null before processing.

NFCPaymentError | Error | null

Error from the most recent scan or process call.

() => void

Clears paymentRequest, processedPayment, and error — resets the hook to idle.

() => void

Clears only the error state.

processPaymentRequest params

string

required

The paymentId from the scanned PaymentRequest.

string

required

Transaction hash. Pass an empty string "" for POOL mode (the backend provides the hash). Required for SESSION_KEY mode.

string

The customer’s wallet address. Required only in SESSION_KEY mode.

Example

import { useNFCCustomer, PaymentStatus } from '@taprails/tap-to-pay';
import { View, Text, Button } from 'react-native';

export function CustomerTapScreen() {
  const {
    scanPaymentRequest,
    processPaymentRequest,
    isReading, isProcessing,
    paymentRequest, processedPayment,
    error, clearPayment,
  } = useNFCCustomer();

  const handlePay = async () => {
    await processPaymentRequest(paymentRequest!.paymentId, '');
  };

  if (processedPayment?.status === PaymentStatus.CONFIRMED) {
    return <View><Text>✅ Paid!</Text><Button title="Done" onPress={clearPayment} /></View>;
  }

  if (isProcessing) return <Text>⏳ Processing…</Text>;

  if (paymentRequest) {
    return (
      <View>
        <Text>Amount: {paymentRequest.amount} USDC</Text>
        <Button title="Confirm Pay" onPress={handlePay} />
        <Button title="Cancel" onPress={clearPayment} />
      </View>
    );
  }

  if (error) {
    return <View><Text>{error.message}</Text><Button title="Retry" onPress={clearPayment} /></View>;
  }

  return (
    <Button
      title={isReading ? '📡 Scanning…' : 'Tap to Pay'}
      onPress={scanPaymentRequest}
      disabled={isReading}
    />
  );
}

Get Started

Use Cases

React Native SDK

API

Webhooks

Coverage

Import

Usage

Return Value

processPaymentRequest params

Example

​Import

​Usage

​Return Value

​processPaymentRequest params

​Example

Import

Usage

Return Value

processPaymentRequest params

Example