/react-widgets

Portable React widgets for the PayDirect API. Drop them into any React or Next.js app — no Tailwind, no shadcn/ui, no global CSS required.

Looking for the styled shadcn versions used inside the PayDirect dashboard? Copy them from components/widgets/ in the PayDirect repo.

Install

npm install @paydirectv2/react-widgets

Peer deps: react >= 17, react-dom >= 17.

Quick start

"use client"
import { PayDirectProvider, CheckoutWidget } from "@paydirectv2/react-widgets"

export function Checkout() {
  return (
    <PayDirectProvider apiKey={process.env.NEXT_PUBLIC_PAYDIRECT_API_KEY!}>
      <CheckoutWidget
        amount="10.00"
        description="Order #123"
        returnUrl="https://yourapp.com/orders/123/success"
        cancelUrl="https://yourapp.com/orders/123"
        onSuccess={(payment) => console.log(payment.paymentMethod, payment.id)}
        onError={(err) => console.error(err)}
      />
    </PayDirectProvider>
  )
}

PayDirectProvider props

| Prop | Type | Default | Description | | --------- | --------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKey | string | — | Your PayDirect API key (pd_live_… or pd_test_…). | | baseUrl | string | "https://www.paydirect.com" | API base URL. Set to "" to call same-origin (useful when your Next.js app proxies the API). | | theme | "light" \| "dark" \| "auto" | "auto" | Theme hint exposed on data-paydirect-theme. The widget itself ships dark-on-dark by default; override via the style / className props on widgets. | | onError | (err: string) => void | — | Global error callback. |

CheckoutWidget props

| Prop | Type | Default | Description | | ---------------- | ------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | amount | string | — | Fixed payment amount. Leave blank with showAmountForm to let the customer enter their own. | | description | string | — | Description shown on the receipt and webhook. | | merchantWallet | string | — | Optional. Destination wallet override. If omitted, PayDirect uses the workspace's settlement_address (or your account-level fallback). | | metadata | Record<string, string> | — | Arbitrary metadata stored on the payment and echoed in webhooks. | | returnUrl | string | — | URL the customer is redirected to after a successful payment. | | cancelUrl | string | — | URL the customer is redirected to if they cancel. | | showAmountForm | boolean | true | Show amount input + token selector. Disable for fixed-amount checkouts. | | defaultToken | "USDC" \| "ETH" \| "ADAO" | "USDC" | Default crypto token to suggest. | | onSuccess | (payment) => void | — | Called when the payment is successfully created (not when it settles — listen to webhooks for that). | | onError | (error: string) => void | — | Failure callback. | | style | React.CSSProperties | — | Style overrides applied to the outer card. | | className | string | — | Class name applied to the outer card (composes after default inline styles). |

How does this differ from the in-repo widgets?

| Widget source | Styling | Use when | | ------------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------- | | /react-widgets (this package) | Self-contained inline styles, no deps | You want a one-line install in any app | | components/widgets/ in the PayDirect monorepo | Tailwind + shadcn/ui + lucide-react | You have a Tailwind+shadcn project and want pixel-matched UI |

Both call the same POST /api/v1/payments endpoint and accept the same payment options — they are interchangeable from the API's perspective.

License

MIT