nodebb-ucashpay

A NodeBB plugin that adds a U.CASH Pay / tip button to forum posts and user profiles. Readers can send crypto or card payments to post authors and members in one click. Non-custodial: payments go straight to the author's own pay.u.cash store, never to a third party.

• One-click tip button on every post (and optionally on profiles)
• Crypto (Bitcoin, EVM, and more) and fiat cards via the author's own Stripe
• Hosted, branded checkout at pay.u.cash opens in a popup, so the reader never leaves your forum
• Non-custodial: only a publishable store Cloud Token is used, never a server secret
• Optional server-tracked checkouts so each tip is reconcilable by external_reference (idempotent)
• Admin settings page under Extend -> Plugins -> U.CASH Pay

---

How it works

The button links to the U.CASH hosted checkout (https://pay.u.cash/embed.php) with the store Cloud Token, amount, currency, and a reference back to the post or profile. The store Cloud Token is publishable: it is safe to put in the browser, just like a Stripe publishable key. No private keys ever touch the forum.

When the optional server-tracked checkouts setting is on, the button instead hits a NodeBB route that calls POST https://pay.u.cash/payment/ajax.php (function=create-transaction, idempotent=1) and redirects to the returned payment URL. That lets you reconcile paid tips back to NodeBB content using the external_reference (nodebb:post:<pid> or nodebb:profile:<uid>).

Requirements

• A running NodeBB v2.8+ or v3.x forum
• Node.js 14 or newer
• A pay.u.cash store (see below)

Install

From your NodeBB directory

npm install @ucash/nodebb-ucashpay

Then rebuild assets and restart NodeBB:

./nodebb build
./nodebb restart

Manual install (from this repo)

Clone into NodeBB's node_modules/ and install dependencies:

cd /path/to/nodebb/node_modules
git clone https://github.com/UdotCASH/nodebb-ucashpay.git
cd nodebb-ucashpay
npm install --omit=dev

Then rebuild and restart:

cd /path/to/nodebb
./nodebb build
./nodebb restart

Activate the plugin under Admin -> Extend -> Plugins, then open Admin -> Extend -> Plugins -> U.CASH Pay to configure it.

Configure

1. Go to Admin -> Extend -> Plugins -> U.CASH Pay.
2. Paste your pay.u.cash Store Cloud Token.
3. Optionally set a default currency, amount, and button label.
4. Choose where the button appears (posts and/or profiles).
5. (Optional) Enable Server-tracked checkouts to reconcile tips by reference.
6. Save and rebuild.

The button appears in each post's tool row and (if enabled) on profile pages. Clicking it opens the U.CASH hosted checkout in a centered popup.

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.

Files

• plugin.json - NodeBB plugin manifest (hooks, templates, CSS, settings defaults)
• library.js - hooks: post data, head config injection, ACP menu
• lib/controllers.js - /ucashpay/checkout server route (server-tracked checkouts)
• lib/admin.js - ACP settings page renderer
• public/client/ucashpay.js - renders the button client-side and opens the checkout popup
• public/admin/admin.js - ACP settings form save logic
• templates/admin/plugins/ucashpay.tpl - ACP settings form
• static/style.css - button styles
• test/index.js - contract tests (npm test)

API reference

Two U.CASH Pay endpoints are used (see the pay.u.cash docs for full details):

Client-side hosted pay link (publishable Cloud Token, straight from the browser):

GET https://pay.u.cash/embed.php
  cloud, amount, currency (default USD), title, external_reference, redirect

Server-side tracked checkout (call from the NodeBB route; idempotent per external_reference):

POST https://pay.u.cash/payment/ajax.php
Content-Type: application/x-www-form-urlencoded

function=create-transaction
amount
currency_code
cryptocurrency_code=
external_reference
title
redirect
cloud
idempotent=1

Response: { success: true, response: [paymentUrl, transactionId, ...] }. The payment URL is the array element that starts with http(s)://.

Security notes

• The store Cloud Token is publishable (like a Stripe publishable key). It can only create checkouts for that store; it cannot move funds, read balances, or change settings.
• Payments are non-custodial: funds settle directly to the addresses the author configured in pay.u.cash. This plugin and NodeBB never hold funds.
• If you enable server-tracked checkouts, the same publishable token is sent server-side to create-transaction. No private keys are involved.
• external_reference values are scoped (nodebb:post:<pid>, nodebb:profile:<uid>) so tips map cleanly back to content.

Publish (maintainers)

This repo is the source of truth. To publish to npm from a clean checkout:

npm version patch     # or minor / major
npm publish --access public

Tag the release and push:

git push --follow-tags

License

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