solana-ucashpay

Create U.CASH Pay checkouts for Solana users. A Solana Pay-style alternative that supports multiple coins plus fiat cards, fully non-custodial.

buildCheckout() returns a hosted pay.u.cash checkout link, and a drop-in Solana wallet-adapter button opens it. Use it anywhere you would have generated a solana: URL, but want multi-coin support, card acceptance, and merchant-controlled settlement.

• Non-custodial: the merchant holds their own keys and receive addresses. Funds never touch U.CASH custody.
• Publishable token: the Store Cloud Token is safe to ship in a browser, dApp, or mobile wallet.
• Multi-coin + cards: buyers pay in SOL, USDC, BTC, ETH, stablecoins, or by card via the merchant's own Stripe.
• Server-tracked (optional): create idempotent, reconcilable checkouts from a server route.

---

Install

npm install solana-ucashpay
# or
pnpm add solana-ucashpay
# or
yarn add solana-ucashpay

Peer deps (optional, only if you use the React button): react, @solana/web3.js, @solana/wallet-adapter-base.

---

Quick start

1. Client-side hosted checkout (publishable token, no server)

The simplest path. Build a hosted pay.u.cash link straight from the browser or dApp using the Store Cloud Token.

import { buildCheckout, openCheckout } from 'solana-ucashpay';

const url = buildCheckout({
  cloud: 'st_your_store_cloud_token', // publishable
  amount: 19.99,
  currency: 'USD',
  title: 'Pro plan (1 month)',
  external_reference: 'order_12345',
  redirect: 'https://yourapp.com/thanks',
});

// url => https://pay.u.cash/embed.php?cloud=st_...&amount=19.99&currency=USD&...

openCheckout({ cloud: 'st_your_store_cloud_token', amount: 19.99 });

2. Solana wallet-adapter button (React)

import { UcashPayButton } from 'solana-ucashpay/react';

function Checkout({ connected }) {
  return (
    <UcashPayButton
      cloud="st_your_store_cloud_token"
      amount={25}
      currency="USD"
      title="NFT mint"
      external_reference="mint_88"
      redirect="https://yourapp.com/success"
      label="Pay with U.CASH"
    />
  );
}

The button builds the hosted link and opens it. Pair it with your Solana wallet provider (@solana/wallet-adapter-react) so the connected wallet funds the on-chain leg of the payment on the U.CASH checkout page.

3. Server-side tracked checkout (idempotent)

Call from a Node.js / edge route to get back a tracked paymentUrl and a U.CASH transactionId. Retry-safe per external_reference.

import { createCheckout } from 'solana-ucashpay';

const { paymentUrl, transactionId } = await createCheckout({
  cloud: 'st_your_store_cloud_token',
  amount: 49.0,
  currency: 'USD',
  title: 'Order #1001',
  external_reference: 'order_1001', // idempotency key
  redirect: 'https://yourapp.com/thanks',
  // cryptocurrency_code: 'USDC', // optional: pin the coin
});

// redirect the buyer to paymentUrl, store transactionId for reconciliation

---

API

buildCheckout(input): string

Returns the hosted pay.u.cash/embed.php link. Publishable-token path.

Field	Type	Required	Notes
cloud	string	yes	Store Cloud Token (publishable)
amount	number / string	yes	Amount in currency
currency	string	no	Defaults to USD
title	string	no	Shown on the checkout
external_reference	string	no	Your order id
redirect	string	no	Post-payment return URL

createCheckout(input): Promise<{ paymentUrl, transactionId? }>

Server-only. POSTs to pay.u.cash/payment/ajax.php with function=create-transaction and idempotent=1. Accepts an optional cryptocurrency_code to pin the coin.

<UcashPayButton /> (solana-ucashpay/react)

Props: all buildCheckout fields plus label, className, style, autoOpen (default true), onUrl(url), onClick(url).

---

How it compares to Solana Pay

	Solana Pay	solana-ucashpay
Transport	solana: URL / QR	Hosted pay.u.cash link (or QR / wallet button)
Coins	Solana only (SPL)	Multi-coin: SOL, USDC, BTC, ETH, stablecoins, and more
Fiat cards	No	Yes, via the merchant's own Stripe
Custody	Non-custodial	Non-custodial (merchant holds keys + receive addresses)
Receive address	Hardcoded in URL per request	Configured once per store (raw, ENS, UD, or FIO)
Server tracking	Manual / off-chain	Built-in, idempotent per external_reference
Wallet UX	Wallet must parse solana: scheme	Opens a hosted page any wallet or browser can render

solana-ucashpay is a pragmatic alternative when you want Solana-native buyers but also need other coins, card fallback, or server-side reconciliation without hand-rolling a transaction-request format.

Honest limitations

• No automatic crypto recurring billing. On-chain crypto payments are pull-free; recurring billing is supported for card payments via the merchant's Stripe, not for native crypto. Implement crypto subscriptions with an explicit per-cycle checkout.
• Buyer coin choice. When cryptocurrency_code is empty, the buyer selects the coin on the hosted page from the store's configured set.
• Wallet leg is external. This library builds and opens the hosted checkout. The actual on-chain signing happens on the U.CASH page using whatever wallet the buyer connects there.

---

Set up your pay.u.cash account

1. Sign up at pay.u.cash, then click the verification link in the email.
2. Set receive addresses under Settings -> Addresses (raw address, ENS, Unstoppable Domains, or FIO).
3. Create a store under Account -> Stores and copy its Store Cloud Token (use the store-level token, not the account-wide one).
4. For fiat cards, connect your own Stripe under Settings -> Payment processors.

---

Build & publish

This repo ships the packaging files; it is not published to a registry by these steps. To build locally:

npm install
npm run build   # outputs dist/ via tsup (ESM + CJS + .d.ts)

To publish to npm when you are ready:

npm version 0.1.0
npm publish --access public

The pre-publish hook runs the build automatically.

---

License

MIT (c) 2026 U.CASH. See LICENSE.