npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@tuwaio/nova-payments

v0.6.1

Published

L8 payments package of Nova UI Kit (TUWA): the checkout of Quasar Payments invoices, with crypto payments from a wallet or a QR code, in a modal, inline or on a page.

Readme

@tuwaio/nova-payments

NPM Version License

@tuwaio/nova-payments is the checkout of Quasar Client, built on Nova UI Kit. It renders the checkout of a Quasar Payments invoice from its checkout token: the order with its lines, tax and deadline, the steps of the payment and its outcome, in a modal (a sheet from the bottom on a phone), in the page, or on a page of its own. It keeps no payment state of its own: the checkout store of @tuwaio/quasar-sdk/checkout reads the invoice and follows it, and no secret key reaches the browser.

[!IMPORTANT] Docs only, not live in production: Quasar Payments is still being built, so what this page describes is not available yet and may change.

[!NOTE] The package is in development: native speakers review the translations of the checkout before the stable release.


💾 Installation

pnpm add @tuwaio/nova-payments @tuwaio/quasar-sdk @tuwaio/nova-core @tuwaio/nova-connect @tuwaio/nova-transactions @tuwaio/satellite-react @tuwaio/satellite-core @tuwaio/pulsar-core @tuwaio/orbit-core zustand react framer-motion @radix-ui/react-dialog @web3icons/react @web3icons/common clsx tailwind-merge

The checkout connects wallets through Nova Connect (NovaConnectProvider of @tuwaio/nova-connect, with its own peers): the app's, or Nova's own when the app has no wallet connection (see "Wallet connection" below). Apps that connect wallets differently pass onConnectWallet, and without either the buyer pays with a QR code.

Import the stylesheets of @tuwaio/nova-core (theme variables), of @tuwaio/nova-transactions (the confirm and paid steps reuse its progress) and of this package (Tailwind CSS v4 utilities prefixed with novapay:):

@import '@tuwaio/nova-core/dist/index.css';
@import '@tuwaio/nova-transactions/dist/index.css';
@import '@tuwaio/nova-payments/dist/index.css';

With Nova's own connection, also import @tuwaio/nova-connect/dist/index.css for its connect modal.

The checkout is drawn in the look of Nova UI Kit 0.15: paper and ink, square, with the pixel icons of @tuwaio/nova-icons (installed with this package). Its icons come from the icon set of NovaIconsProvider of @tuwaio/nova-core, so an app that gave Nova another set (heroicons of @tuwaio/nova-core/heroicons) gets it in the checkout too. The icons only the checkout draws (a lock, a QR code, a download and others) are optional in a set: the Heroicons set has them from @tuwaio/nova-core 0.15.1, and with a set that has none, or an older @tuwaio/nova-core, they stay the pixel ones. The names of a seller, a wallet and a network keep their own letters inside the buttons, whose words are in capitals.


🚀 Usage

Issue the invoice on your server with @tuwaio/quasar-sdk and pass its checkoutToken to the checkout:

'use client';

import { PaymentCheckout } from '@tuwaio/nova-payments';
import { useState } from 'react';

export function Checkout({ token }: { token: string }) {
  const [open, setOpen] = useState(false);
  return (
    <>
      <button type="button" onClick={() => setOpen(true)}>
        Pay
      </button>
      <PaymentCheckout token={token} open={open} onOpenChange={setOpen} />
    </>
  );
}

display="inline" renders it in the page. display="page" is the whole page, as the Quasar payment page shows it: a sheet 880 px wide, centered in the window (min-height: 100svh; a page with a header of its own sets --novapay-page-height on an ancestor, for example calc(100svh - 64px)), that grows downward with its step and scrolls nothing inside, full-bleed under 640 px. NovaPaymentsProvider sets the Quasar API for a Community Edition node (baseUrl) and replaces labels.

To pay from a wallet in the browser, give the provider the chain adapters of your app (@tuwaio/nova-payments/evm needs @wagmi/core and viem; @tuwaio/nova-payments/solana needs @solana/kit, @solana-program/system, @solana-program/token and @tuwaio/orbit-solana) and, optionally, your Pulsar store: every payment of a checkout goes to it, and Nova Transactions shows its toast (one the wallet sends at once, one paid with a QR code or a relayed signature once Quasar records it).

'use client';

import { NovaPaymentsProvider } from '@tuwaio/nova-payments';
import { paymentsEVMAdapter } from '@tuwaio/nova-payments/evm';
import { paymentsSolanaAdapter } from '@tuwaio/nova-payments/solana';
import type { Transaction } from '@tuwaio/pulsar-core';
import type { Config } from '@wagmi/core';
import type { ReactNode } from 'react';

export function Payments({
  wagmiConfig,
  injectExternalPendingTxs,
  children,
}: {
  wagmiConfig: Config;
  injectExternalPendingTxs: (transactions: Transaction[]) => Promise<void>;
  children: ReactNode;
}) {
  return (
    <NovaPaymentsProvider
      adapters={[
        paymentsEVMAdapter(wagmiConfig),
        paymentsSolanaAdapter({ rpcUrls: { devnet: 'https://api.devnet.solana.com' } }),
      ]}
      pulsar={{ injectExternalPendingTxs }}
    >
      {children}
    </NovaPaymentsProvider>
  );
}

Wallet connection: the app's or Nova's own

Nova Payments brings its own wallet connection only when the app has none. NovaPaymentsProvider decides once, on its first render, and usePaymentsConnection tells which:

| Above NovaPaymentsProvider | Wallet, network and connect modal | Payment adapters | | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------ | | The app's SatelliteConnectProvider and NovaConnectProvider | The app's (app), with its SIWX; Nova mounts nothing of its own | adapters | | The app's SatelliteConnectProvider only | The app's wallet (appStore); "Connect wallet" calls onConnectWallet; never a second store | adapters | | Nothing, and ownConnection is given | Nova's own (own): a Satellite store, the watchers and a Nova Connect modal, never with SIWX | ownConnection.adapters | | Nothing | None (none): QR codes, and onConnectWallet | adapters |

Inside an app with Satellite Connect and Nova Connect, add only NovaPaymentsProvider with adapters on the wagmi config of the app's Satellite EVM adapter (as above): the checkout and the refunds show the app's wallet, "Connect wallet" opens the app's modal, and a payment on another network switches that wallet. If the app signs in with SIWX through Nova Connect, set siwx.sessionScope: 'account' there when its server binds a session to the address only, so a network switch made by the checkout does not ask the wallet to sign in again (see @tuwaio/nova-connect). A NovaPaymentsProvider inside another one's own connection uses that connection, so two stores never stack, and without adapters it pays with those of the provider above.

A page without a wallet connection (a payment page, an admin page) gives ownConnection, created once at module level. Nova's store runs Satellite's start-up only with autoConnect, so it never drops the wallet of another tab or of the host page. It lives as long as the page, one per Satellite adapter, as the wagmi config does: a checkout closed and opened again, another page or a second provider on the same adapters shows the wallet still connected. autoConnect: true reconnects the last wallet once per page load, with Satellite's start-up (with @tuwaio/satellite-core 0.11.1 or later, without a permission prompt and without disconnecting wallets this page did not connect; earlier versions disconnect every wallet of the adapters first); without it, the connect modal hides "Remember this wallet", since nothing would reconnect the wallet. Nova's own connection and its Nova Connect modal load on demand, so an app that does not use them does not download them.

'use client';

import { EVMConnectorsWatcher } from '@tuwaio/nova-connect/evm';
import { SolanaConnectorsWatcher } from '@tuwaio/nova-connect/solana';
import { type NovaPaymentsOwnConnection, NovaPaymentsProvider, PaymentCheckout } from '@tuwaio/nova-payments';
import { paymentsEVMAdapter } from '@tuwaio/nova-payments/evm';
import { paymentsSolanaAdapter } from '@tuwaio/nova-payments/solana';
import { createDefaultTransports, satelliteEVMAdapter } from '@tuwaio/satellite-evm';
import { satelliteSolanaAdapter } from '@tuwaio/satellite-solana';
import { createConfig, createStorage, injected, noopStorage } from '@wagmi/core';
import { base, type Chain, mainnet } from 'viem/chains';

const chains = [mainnet, base] as readonly [Chain, ...Chain[]];
const solanaRPCUrls = { mainnet: 'https://api.mainnet-beta.solana.com' };
const wagmiConfig = createConfig({
  chains,
  connectors: [injected()],
  transports: createDefaultTransports(chains),
  ssr: true,
  storage: createStorage({ storage: noopStorage }),
});

const ownConnection: NovaPaymentsOwnConnection = {
  adapter: [satelliteEVMAdapter(wagmiConfig, chains), satelliteSolanaAdapter({ rpcUrls: solanaRPCUrls })],
  watchers: (
    <>
      <EVMConnectorsWatcher wagmiConfig={wagmiConfig} />
      <SolanaConnectorsWatcher />
    </>
  ),
  adapters: [paymentsEVMAdapter(wagmiConfig), paymentsSolanaAdapter({ rpcUrls: solanaRPCUrls })],
  novaConnect: { appChains: chains, solanaRPCUrls, withBalance: true, withChain: true },
};

export function PayPage({ token }: { token: string }) {
  return (
    <NovaPaymentsProvider ownConnection={ownConnection}>
      <PaymentCheckout token={token} display="page" />
    </NovaPaymentsProvider>
  );
}

The full integration with Satellite Connect, SIWX and Pulsar is in the Full-Stack React guide.

Before an EVM payment the buyer's wallet sends itself (paying the gas, or a smart wallet with or without the merchant's paymaster), the wallet confirms the invoice: right after the wallet and the method are chosen, before the price, a step says that it is free and moves no money, sums up what the wallet signs (the invoice, the seller, the amount and the wallet) and opens the wallet's signature request (an EIP-4361 message from Quasar, signed with personal_sign; a smart wallet may ask for its passkey). Quasar credits the wallet's transfers to this invoice only once it signed; one signature per invoice and wallet, so a new price, token or network needs none. A refusal keeps the buyer on the step with the reason and the same button; "Back to methods" returns. A gasless USDC or EURC payment needs no extra window (the signed authorization confirms the wallet), and when the buyer pays the gas of such a method instead, the pay step asks for the confirmation first. The EVM adapter sends a gasless payment itself, from a one-time account: a key it makes in memory for the payment, delegated (EIP-7702) to Simple7702Account, whose one call is the transfer Quasar authorized for the signature, sponsored by the merchant's paymaster; the wallet signs only the authorization, and Quasar signs nothing. Solana payments and automatic charges are unchanged. A chain adapter of your own adds signMessage for it.

The checkout shows a price's receiving address or QR code, and asks the wallet to pay, only once the payee of the price is verified: every place of the address in the quote (the instructions, the EIP-3009 authorization of a gasless payment, the paymaster calls, the Solana Pay link) names one address, the payout record Quasar sends with the quote covers its network and address and is signed by that address's own wallet, and the address is one of your payoutAddresses when you pin them. The chain adapters check the signature in the page: an ordinary EVM wallet's by recovery, a smart wallet's through its contract on the quote's network (ERC-1271, ERC-6492) over the RPC of your wagmi config, a Solana wallet's Ed25519. A price that fails is never shown: the step says that the payment is stopped and that nothing was sent (data-payee-refusal names the reason). The signature shows that the receiving wallet agreed, not that it is yours: a swap in Quasar's database could carry a record its own wallet signed. Pin your receiving addresses, from your own configuration, to stop that:

<PaymentCheckout
  token={checkoutToken}
  payoutAddresses={['0x52908400098527886E0F7030069857D2E4169EE7', '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU']}
/>

The hosted payment page reads them from the #payout= fragment of its link, which payoutAddresses of the Quasar client of @tuwaio/quasar-sdk adds; against a compromise of Quasar's servers themselves, only a checkout in your own page with the pins holds. A chain adapter of your own adds verifyPayoutRecord; without it the checkout matches the record but leaves its signature unchecked.

After the payment the checkout shows its outcome: confirming, paid with the receipt and the way back to the invoice's successUrl (a visible countdown with "Stay here"; autoReturnSeconds, 0 for none). A payment that fails for good while the buyer watches (reverted, cancelled in the wallet, an expired Solana transaction) stays on the same screen as the failed step, with its transaction, the reason and "Pay again". Underpaid, refunded, expired, cancelled and corrected invoices, and those whose payment needs the seller's review, get their own outcome with a "Contact" link to the seller (onContact replaces it). Every status screen has the same head in the same place (the mark, a chip that names the state, the heading and the amount), so one goes on into the next: the pixels of the Quasar loader fly into the check mark or the cross, the chip changes its color and word, the heading morphs, the steps run on, the fill of the main button comes in over "Close" and the receipt opens. On a phone, where the checkout is as tall as its step, its height glides from one status screen to the next instead of jumping. With prefers-reduced-motion, or config.animation.disabled, the screens just change. onPaid tells the page once the invoice is paid; fulfil orders from the invoice.paid webhook on your server. Closing the checkout before anything is sent asks first. The countdown to the invoice's deadline stays in the order through every step, also while the wallet signs and the payment confirms, and goes once the payment succeeded or the invoice has another outcome; when the deadline passes while the payment confirms, it stays at 00:00 and the confirm step says that a payment sent in time is being confirmed (from Quasar's word on that payment, else its paymentCountsUntil, else the page's clock), or that a payment arriving after the invoice closes waits for the seller to accept or return it. The buyer is never invited to pay twice: a page reopened while a payment of the invoice is on its way shows that payment confirming, and a payment Quasar could not confirm asks the buyer to check the wallet before paying again instead of offering the payment. The checkout says that Quasar checks the payment again for 24 hours and records it for the seller only while Quasar still reads it again (not found, no receipt in time, replaced); for a payment Quasar does not read again (a relay operation lost, an unknown failure, no result on chain within 24 hours, a hand-over the page gave up after an hour) it asks the buyer to contact the seller with the transaction hash, which it shows. A payment counts as sent once the wallet returned its hash: an invoice that expires or is cancelled while a payment may still arrive never says that nothing was charged, and a transaction that does not pay the invoice (a wrong amount or recipient) is named as such, with the seller to contact if money left the wallet. A QR code the checkout showed may have been paid from a phone, so an invoice that expires or is cancelled after it never says that nothing was charged either. A transaction the page of another invoice handed over first (EVM invoices share the seller's address) is credited by Quasar to the invoice the wallet that sent it confirmed: the checkout follows it, offers no payment meanwhile and shows its hash for the seller, and says that it pays another invoice if Quasar credits it there. A transfer from a wallet that did not confirm the invoice pays no invoice: the checkout says that the seller returns it to the wallet that sent it (the invoice stays payable from the wallet that confirmed it), never that the seller checks it. A payment the network confirmed that Quasar has not recorded yet is named with its hash for the seller, never as a failure, and no payment is offered; the checkout says that Quasar tries again daily (for 30 days) only while Quasar says it does. On an expired or cancelled invoice the checkout says until when the page follows a payment on its way; later, a reload shows the outcome.

Customization

Besides the --tuwa-* theme variables of @tuwaio/nova-core and the labels, customization of PaymentCheckout adds classes to its parts from the state of the checkout (classNames) and replaces parts (components): the header, the order, the steps, the token and network options, the main button, the QR code, the outcome icon, the status chip (classNames.statusChip), or whole screens by name (failed among them). A replacement reads the checkout with useCheckoutContext. A replaced screen that shows WalletPrompt while the wallet asks puts it in place of its step: it hides the step meanwhile (display: none and inert, so the step keeps its state) and passes the step's height as stepHeight, so the checkout keeps its height on a phone. Classes are added after the default ones; change a color a part already sets with the theme variables or by replacing the part. handlers wrap the actions of the buyer (onMethodSelect, onQuote, onSubmit, onLocaleChange: call proceed() to go on, or do something else) and tell what happened (onStatusChange, onError, onExpire); config turns off animations, the steps or the balance check and sets the minutes of the deadline announcements; childCustomizations styles the Nova Transactions parts of the confirm and paid steps.

'use client';

import { type CheckoutPrimaryButtonProps, PaymentCheckout } from '@tuwaio/nova-payments';

function ShopButton({ busy, children, className, ...props }: CheckoutPrimaryButtonProps) {
  return (
    <button
      type="button"
      {...props}
      disabled={props.disabled || busy}
      aria-busy={busy || undefined}
      className={`shop-button ${className ?? ''}`}
    >
      {children}
    </button>
  );
}

export function BrandedCheckout({ token }: { token: string }) {
  return (
    <PaymentCheckout
      token={token}
      display="inline"
      customization={{
        classNames: { tokenOption: ({ selected }) => (selected ? 'shop-selected' : undefined) },
        components: { PrimaryButton: ShopButton },
      }}
    />
  );
}

Refunds

RefundButton refunds a paid invoice from the merchant's connected wallet: what to refund (an amount of the invoice currency or everything received), a wallet of the payment's network, the confirmation with the wallet's balance and the network fee, the wallet's prompt, then Quasar follows the transaction and issues the credit note. It takes a refund store of @tuwaio/quasar-sdk/checkout whose three calls run on your server with the secret key (Server Actions calling quasar.payments.refund, submitRefund and getRefund). Put it inside NovaPaymentsProvider: it uses the provider's wallet connection (the app's, or Nova's own) and its adapters; without Nova Connect, onConnectWallet connects the wallet. A wallet on another network is asked to switch first; one that holds too little is asked nothing; a refund the wallet sent but Quasar did not take is handed over again, never sent twice. RefundDialog is the same window opened by your own button, params skips the amount step, and onRecord offers your form for a refund sent another way.

'use client';

import { RefundButton } from '@tuwaio/nova-payments';
import { createRefundStore, type RefundStoreOptions } from '@tuwaio/quasar-sdk/checkout';
import { useState } from 'react';

export function Refund({ invoiceId, number, calls }: { invoiceId: string; number: string; calls: RefundStoreOptions }) {
  // One store per invoice: the refund goes on while the window is closed
  const [store] = useState(() => createRefundStore(calls));
  return <RefundButton store={store} invoiceId={invoiceId} invoice={number} currency="USD" />;
}

🌍 Languages and accessibility

The checkout speaks the six languages of Quasar invoices: English, Ukrainian, Simplified Chinese, Spanish, Italian and German. It follows the language of the invoice, or the language of the page around it when the app gives one (locale of PaymentCheckout, a BCP 47 tag such as the lang of <html>: uk-UA opens the checkout in Ukrainian; a language the checkout does not have is left to the invoice). The buyer changes it in the menu next to the close button, which also sets the language of the documents still to be issued; their pick wins over the page until the page changes its language. customization.handlers.onLocaleShown tells the app the language the checkout shows, for its own <html lang> or the labels of Nova around the checkout. Each language but English is a file of its own that the page downloads the first time it shows that language, so a checkout in one language does not carry the other five; the first screen waits for it, so it never flashes in English. A language the package does not have can be added with customization.labels.transform of NovaPaymentsProvider. The checkout aims at WCAG 2.2 AA: the steps are an ordered list with the current one marked, the deadline is announced 10, 5 and 1 minutes before it ends while the buyer can still pay, and animations follow prefers-reduced-motion. Everything works from the keyboard: Tab moves between groups, the arrow keys between options, Enter continues, and Escape closes (asking first while nothing is sent; Escape on that question stays). Each new step takes the focus on its heading, so screen readers read it; the focus stays in the modal and returns to the element that opened it. Every Storybook story of the checkout is checked with axe (WCAG 2.2 AA rules, also at 320 px wide) and the keyboard scenarios run as tests on every change; a screen reader pass with VoiceOver and NVDA comes before the first stable release.


🗄️ Browser Storage

The checkout and the refund window save nothing to localStorage or cookies. Until Quasar takes or refuses a payment transaction the wallet sent, the checkout store of @tuwaio/quasar-sdk keeps its hand-over in sessionStorage (the browser tab, until it closes) under quasar-sdk:checkoutHandOvers:<checkout token>: the transaction hash, the sending wallet, the wallet connector and when it was sent, so a page closed or reloaded before Quasar answered hands the payment over again (nothing is kept with your own api). A sponsored batch the wallet took has no hash yet: it is kept in sessionStorage under nova-payments:sponsoredBatches for 35 minutes or until its hash comes (the invoice ID, the batch ID, the wallet, the wallet connector, the method and what it pays), so a reload follows it instead of offering to pay next to it. Until Quasar takes it or refuses it for good, a refund transaction the wallet sent is kept by the refund store of @tuwaio/quasar-sdk in sessionStorage under quasar-sdk:refundHandOvers: the refund and invoice IDs, the refund's instructions, the transaction hash and the sending wallet, so a reload hands it over instead of having the wallet send the refund again. A payment it hands over to your Pulsar store is kept by that store (createPulsarStore persists its pool under its own name). The key of the one-time account that sends a gasless payment stays in memory: it is never saved or sent.

Nova's own connection (ownConnection) keeps the connected wallet in sessionStorage until the tab closes (orbit-core:lastConnectedConnector and orbit-core:recentlyConnectedConnectorsListHelpers, see @tuwaio/satellite-core), and in localStorage with rememberWallet: true or, with autoConnect, when the buyer ticks "Remember this wallet" in its connect modal. Every Satellite store of the site shares these keys: connecting a wallet there that is not remembered moves orbit-core:lastConnectedConnector and that wallet's entry of the list out of localStorage, and disconnecting removes the last connection, so another Satellite app on the same origin forgets the wallet it remembered. wagmi keeps its own wagmi.* keys in localStorage unless the wagmi config uses createStorage({ storage: noopStorage }), as in the example above. Inside the app's connection, the app's stores keep them.

🌐 External Services

The checkout routes of the Quasar API (baseUrl, Quasar Cloud by default): GET /v1/payments/checkout/{token}, its event stream and logo, and the POST routes of the steps (buyer, locale, payer-proof/message, payer-proof, quote, submit, relay/authorize, relay; the wallet calls the paymaster route for sponsored calls, and so does the page's one-time account of a gasless payment). The EVM adapter reads balances and fee estimates through the RPC transports of your wagmi config (and the nonce and code of a one-time account), the Solana adapter through its rpcUrls (else the public endpoint of the cluster); links to transactions open the chain's block explorer (the explorer of the wagmi chain, the Solana Explorer). A refund calls only your server (the calls of its store); the adapters read the merchant wallet's balance and the fee the same way. Nova's own connection loads what its Satellite adapters and its Nova Connect modal load (see @tuwaio/nova-connect) through the RPC of its wagmi config and rpcUrls. The wallet asks the buyer, or the merchant for a refund, before every signature or transaction.


🤝 Contributing & Support

Contributions are welcome! Please read our main Contribution Guidelines.

📄 License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.