@speciehq/widget

Embeddable USDC checkout for Arc.

npm install @speciehq/widget

import { SpecieCheckout } from "@speciehq/widget";

<SpecieCheckout
  paymentId={payment.id}
  baseUrl="https://checkout.example.com"
  onSuccess={(p) => router.push(`/thanks?id=${p.id}`)}
/>

Why there is no amount prop

Creating a payment requires the secret API key. A widget that accepted an amount would either need that key in the browser — where anyone could read it and issue payments against your account — or let the payer choose what to pay.

So your server creates the payment with @speciehq/sdk and passes the resulting id to the widget. The amount is fixed server-side and the payer cannot alter it. This is the same split as Stripe's PaymentIntent.

The payment id is a 256-bit random value and is safe to expose to the payer; it grants nothing except the ability to see and pay that one payment.

Styling

The widget renders inside a shadow root with its own stylesheet, so your CSS cannot break it and its CSS cannot leak into your page. It follows the system light or dark preference and needs no build step, CSS import, or bundler plugin.

Props

| Prop | | | |---|---|---| | paymentId | required | From payments.create on your server | | baseUrl | | Origin of your Specie deployment | | pollIntervalMs | 4000 | How often status is refreshed | | onStatusChange | | Called on every status transition | | onSuccess | | Called once when the payment is fully paid |

onSuccess is a UI convenience, not proof of payment. Fulfil orders from the payment.confirmed webhook, which is signed and comes from your server. A browser callback can be forged by anyone with devtools.

Requirements

React 18 or 19. The customer needs no wallet: the widget shows a deposit address and QR they can pay from anywhere, with a link to the hosted page for wallet payment.