Skip to main content
usePaymentStatus polls the TapRails backend for payment confirmation. Use this after initiating a payment to know when it’s been confirmed on-chain.

​
Import

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

​
Usage

const {
  startPolling,
  stopPolling,
  fetchStatus,
  isPolling,
  status,
  isConfirmed,
  isFailed,
  txHash,
  confirmedAt,
  error,
  clearError,
  reset,
} = usePaymentStatus({
  paymentId: 'pay_abc123',  // optional — can also pass to startPolling()
  pollingInterval: 2000,    // ms between polls (default: 2000)
  autoStart: false,         // start polling immediately (default: false)
});

​
Options

​
paymentId
string
The payment ID to poll. Can also be passed to startPolling() instead.
​
pollingInterval
number
Interval between status checks in milliseconds. Default: 2000 (2 seconds).
​
autoStart
boolean
If true, polling starts immediately on mount using the provided paymentId. Default: false.

​
Return Value

​
startPolling
(paymentId?: string) => void
Starts polling. Optionally accepts a paymentId to override the one from options.
​
stopPolling
() => void
Stops the polling interval.
​
fetchStatus
(paymentId: string) => Promise<PaymentStatusResponse>
One-shot status fetch without starting continuous polling.
​
isPolling
boolean
true while the polling interval is active.
​
status
PaymentStatusResponse | null
The latest status response from the backend.
​
isConfirmed
boolean
true when status.status === 'confirmed'.
​
isFailed
boolean
true when status.status === 'failed'.
​
txHash
string | undefined
On-chain transaction hash once confirmed.
​
confirmedAt
number | undefined
Unix timestamp (ms) of confirmation.
​
error
APIError | null
Error from the most recent poll.
​
clearError
() => void
Clears the error state.
​
reset
() => void
Stops polling and clears all state.

​
Example

import { useEffect } from 'react';
import { usePaymentStatus } from '@taprails/tap-to-pay';

export function PaymentConfirmation({ paymentId }: { paymentId: string }) {
  const { startPolling, stopPolling, isConfirmed, isFailed, txHash, isPolling } =
    usePaymentStatus({ pollingInterval: 3000 });

  useEffect(() => {
    startPolling(paymentId);
    return () => stopPolling();
  }, [paymentId]);

  useEffect(() => {
    if (isConfirmed) {
      stopPolling();
      console.log('Confirmed! tx:', txHash);
    }
    if (isFailed) {
      stopPolling();
      console.log('Payment failed');
    }
  }, [isConfirmed, isFailed]);

  if (isConfirmed) return <Text>✅ Confirmed — {txHash?.slice(0, 10)}…</Text>;
  if (isFailed) return <Text>❌ Payment failed</Text>;
  if (isPolling) return <ActivityIndicator />;

  return null;
}