@firma/pay

Quick Start

Go from zero to a live Firma Pay checkout in minutes. This guide covers the minimum integration — install, render, and handle payment confirmation.

1. Install

pnpm add @firma/pay
or
npm install @firma/pay
or
yarn add @firma/pay

View @firma/pay on npm →

2. Add the checkout widget

Create a client component (or page) that renders PayWithFirma. Pass your merchant username, a unique order ID, and the amount in Firma stablecoins.

Checkout.tsx
'use client';

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

export function Checkout() {
  return (
    <PayWithFirma
      receiverUsername="merchant"
      orderId="VP9G"
      amount="10.00"
      currency="USD"
      onPaymentFinalized={(txid) => {
        console.log('Payment finalized:', txid);
        // Update your order status, fulfill, redirect, etc.
      }}
    />
  );
}

3. Test with Firma Wallet

When the widget renders, customers tap Pay with Firma or scan the QR code with Firma Wallet. Payment detection runs automatically — you will see a pulse when the tx hits the mempool and a checkmark when it finalizes.

Try it live on the Demo page without writing any code.

Order IDs

Every checkout needs a unique orderId (max 100 UTF-8 bytes). Firma Pay encodes it in the FPAY EMPP push so incoming payments can be matched reliably. Use your internal order number, invoice ID, or cart session key.

Receiver

receiverUsername can be any valid ecash: address or your Firma username (with or without @).

Next steps