Payment Detection

PayWithFirma watches the receiver address over Chronik WebSocket and matches incoming FIRMA transfers against your order. You can also use the lower-level usePaymentWatcher hook for custom UIs.

How PayWithFirma detects payments

When the QR screen is shown, the component:

1. Opens a Chronik WebSocket subscription for receiverUsername
2. Inspects incoming transactions for:
   • FIRMA sent to the receiver in the expected amount
   • An FPAY EMPP push with a matching orderId
3. Shows a pulse animation on TX_ADDED_TO_MEMPOOL
4. Shows a purple checkmark on TX_FINALIZED (pre-consensus)
5. Closes the WebSocket and calls onPaymentFinalized(txid)

Chronik failover

By default, the widget connects to https://chronik.firma.cash. Pass chronikUrls to override with your own endpoints — the watcher tries each URL in order until one connects.

Custom integrations

For headless or server-driven flows, use isMatchingFirmaPayment to verify transactions yourself. See the API Reference.