# Firma Pay — @firma/pay

> Firma Pay is the easiest way to end fees and chargebacks for your eComm business. Drop a React checkout widget into any site, accept USD/CHF/EUR Firma payments with zero transaction fees, and get real-time confirmation via Chronik — no card networks, no chargebacks, no rolling reserves.

## Why merchants choose Firma Pay

- **0% transaction fees** — Firma Pay has no per-transaction card or platform fees. Keep more of every sale.
- **No chargebacks** — Firma payments are final settlement on-chain. No dispute windows or rolling reserves.
- **Real-time confirmation** — Chronik WebSocket detects mempool and finalized payments in seconds.
- **Multi-currency checkout** — USD, CHF, and EUR Firma stablecoins with a single `currency` prop.
- **Order tracking built in** — FPAY EMPP encodes your `orderId` in every payment for reliable matching.
- **Drop-in React widget** — `<PayWithFirma>` handles QR codes, deep links, and payment watching.
- **npm package** — Install with pnpm, npm, or yarn (see commands below).

## Quick install

```bash
pnpm add @firma/pay
```

```bash
npm install @firma/pay
```

```bash
yarn add @firma/pay
```

```tsx
import '@firma/pay/firma-pay.css';
import { PayWithFirma } from '@firma/pay';

<PayWithFirma
  receiverUsername="merchant"
  orderId="VP9G"
  amount="10.00"
  currency="USD"
  onPaymentFinalized={(txid) => console.log('Paid!', txid)}
/>
```

## Documentation

- [Introduction](https://pay.firma.cash/)
- [Installation](https://pay.firma.cash/docs/installation)
- [Quick Start](https://pay.firma.cash/docs/quick-start)
- [PayWithFirma](https://pay.firma.cash/docs/pay-with-firma)
- [Payment Detection](https://pay.firma.cash/docs/payment-detection)
- [Next.js](https://pay.firma.cash/docs/nextjs)
- [API Reference](https://pay.firma.cash/docs/api-reference)
- [LLMs](https://pay.firma.cash/docs/llms)
- [Live Demo](https://pay.firma.cash/demo)
- [LLMs index (this file)](https://pay.firma.cash/llms.txt)

## Package exports

```typescript
import {
  PayWithFirma,
  usePaymentWatcher,
  getOrderIdUtf8ByteLength,
  isValidOrderId,
  isEcashAddressReceiver,
  getInvalidEcashAddressError,
  FPAY_ORDER_ID_BYTES_MAX,
  encodeFpayEmpp,
  encodeFpayEmppRaw,
  decodeFpayEmpp,
  decodeFpayEmppFromPush,
  decodeFpayEmppRaw,
  buildFirmaPayQrPayload,
  isMatchingFirmaPayment,
} from '@firma/pay';
```

## Payment detection flow

1. Open a Chronik WebSocket subscription for `receiverUsername` (an `ecash:` address or Firma username).
2. Match incoming FIRMA transfers with the expected amount and FPAY `orderId`.
3. Pulse animation on `TX_ADDED_TO_MEMPOOL`; checkmark on `TX_FINALIZED`.
4. Call `onPaymentFinalized(txid)` and close the WebSocket.

## Next.js note

`@firma/pay` uses `ecash-lib` (WASM). Mark routes that render `PayWithFirma` as dynamic:

```tsx
export const dynamic = 'force-dynamic';
```

## Links

- Documentation: https://pay.firma.cash
- npm: https://www.npmjs.com/package/@firma/pay
- Firma Wallet: https://firma.cash