kofi-ucashpay

A drop-in "Buy me a coffee"-style support widget powered by U.CASH Pay. Accept crypto and cards. Non-custodial: payouts go straight to your own wallets.

One zero-dependency script (ucash-tip.js) renders a floating tip button and a modal amount picker, then opens the U.CASH Pay hosted checkout. No build step, no backend required.

Features

• Zero dependencies, single file (ucash-tip.js), ~6 KB.
• Floating button + modal with preset and custom amounts.
• Crypto (BTC, ETH, USDC, and more) plus fiat cards via your own Stripe.
• Non-custodial. Funds settle to your own receive addresses.
• Configurable via data-* attributes or a JavaScript object.
• Optional server-side helper for tracked, idempotent checkouts.

Quick start (one-line embed)

Add this to any HTML page. Replace YOUR_STORE_CLOUD_TOKEN with your store Cloud Token.

<script src="ucash-tip.js"
        data-cloud="YOUR_STORE_CLOUD_TOKEN"
        data-title="Buy me a coffee"
        async></script>

That is it. A floating button appears, and tips open the U.CASH Pay checkout in a new tab.

Programmatic init

For more control, configure via JavaScript instead of data-* attributes.

<script src="ucash-tip.js"></script>
<script>
  UcashTip.init({
    cloud: "YOUR_STORE_CLOUD_TOKEN",
    currency: "USD",
    title: "Buy me a coffee",
    amounts: [3, 5, 10, 25],   // up to 4 preset amounts
    text: "Support me",         // button label
    color: "#ff5f5f",           // accent color
    position: "right",          // "right" or "left"
    redirect: "https://yoursite.com/thanks",
    external_reference: "tip-blog-2026"  // optional, see server helper below
  });
</script>

Configuration options

Option	Via attribute	Default	Description
cloud	data-cloud	(required)	Your store Cloud Token. Publishable, safe in the browser.
currency	data-currency	USD	Default currency shown in the picker.
title	data-title	Buy me a coffee	Heading shown on the modal and the checkout.
amounts	data-amounts	2,5,10,25	Comma-separated preset amounts (up to 4).
text	data-text	Buy me a coffee	Floating button label.
color	data-color	#ff5f5f	Accent color (button, highlights).
position	data-position	right	right or left.
redirect	data-redirect	(none)	Post-payment redirect URL.
external_reference	data-external-reference	(none)	Optional reference tag for this tip.

Demo

Open index.html in a browser, or serve the folder:

npx serve .
# or
python3 -m http.server 8000

Then visit the printed URL. The demo uses a placeholder token, so replace it with a real store Cloud Token to receive live tips.

How payments work

The widget builds a client-side hosted checkout link:

https://pay.u.cash/embed.php?cloud=...&amount=...&currency=USD&title=...&external_reference=...&redirect=...

The store Cloud Token is publishable: it can only create checkouts that pay you. It cannot read balances, move funds, or change settings. Payouts go to the receive addresses configured on your pay.u.cash store.

Optional: server-side tracked checkouts

By default the widget uses the client-side embed.php link, which needs no backend. If you want a server-tracked transaction per tip (for analytics, webhook reconciliation, or single-use links), use the Node.js helper in server/node.js. It is idempotent per external_reference.

const { createCheckout } = require("./server/node.js");

const { paymentUrl, transactionId } = await createCheckout({
  cloud: process.env.UCASH_CLOUD_TOKEN,
  amount: 5,
  currency: "USD",
  external_reference: `tip-${Date.now()}`, // unique per tip; replays return the same checkout
  title: "Buy me a coffee",
  redirect: "https://yoursite.com/thanks"
});

// Redirect your visitor to paymentUrl, or pass it into UcashTip.buildEmbedUrl()
// for a pre-tracked checkout.

The helper calls POST https://pay.u.cash/payment/ajax.php with function=create-transaction, amount, currency_code, cryptocurrency_code= (empty), external_reference, title, redirect, cloud, and idempotent=1. The payment URL is the response array element that starts with http(s)://.

Tip: keep your Cloud Token out of source control when using the server helper. Load it from an environment variable.

Limitations

• No automatic recurring crypto billing. U.CASH Pay supports one-time tips and card payments. Recurring support ("monthly") is not available out of the box; you would layer your own subscription logic on top (create a checkout on a schedule) and document that to your supporters.
• One widget per page. The floating button mounts once; calling init() multiple times is a no-op after the first mount.

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.

License

MIT. See LICENSE.