flarum-ucashpay

A Flarum extension that adds a U.CASH Pay / tip button to every post on your forum. Visitors pay the post author in crypto or by card through the hosted pay.u.cash checkout. The integration is non-custodial: funds settle straight to the merchant's configured receive addresses and never pass through your Flarum server.

Crypto (BTC, ETH, USDC, and many more) plus optional cards via Stripe. No server secrets required, no webhook plumbing to get started.

Features

• One-click "Tip with U.CASH" button on each post footer.
• Non-custodial: the button opens a hosted pay.u.cash checkout using your publishable Store Cloud Token (safe to ship to the browser, like a Stripe publishable key).
• Configurable mode (Tip / Pay), default amount, currency, and per-author title template ({username}).
• Admin settings panel inside the standard Flarum extension manager.
• Optional server-side tracked checkout for advanced integrations (see below).

Requirements

• Flarum 1.0 or newer (PHP 7.3+ / 8.x).
• A pay.u.cash merchant account with a Store Cloud Token.
• (Optional) Your own Stripe account connected in pay.u.cash for card payments.

Install

Run this in the directory where your Flarum composer.json lives:

composer require ucashpay/flarum-ucashpay:"*"

Then enable U.CASH Pay under Extensions in your Flarum admin dashboard.

Build from source (developers)

The extension ships with its compiled JavaScript bundle checked out of source. If you fork or hack on it, rebuild the frontend:

cd /path/to/flarum-ucashpay
npm install
npm run build

The build outputs js/dist/forum.js and js/dist/admin.js, which extend.php already wires up.

Configure

1. In the Flarum admin, open Extensions -> U.CASH Pay.
2. Paste your Store Cloud Token (the per-store one, e.g. st_...). This token is publishable and safe to expose to the browser.
3. Pick a mode (Tip or Pay), optional default amount, currency, and a title template. Use {username} to insert the post author's display name.
4. Save. A button now appears on every post footer.

When a visitor clicks, the browser opens the hosted pay.u.cash checkout with the token, amount, currency, title, an external_reference of flarum-post-<id>, and a redirect back to the current page. Funds go to your configured pay.u.cash receive addresses.

Usage

Visitors click Tip with U.CASH under any post, choose a coin (or card) on the hosted checkout, and pay. You see the incoming payment in your pay.u.cash dashboard tagged with the originating post id. Because the flow opens pay.u.cash directly from the browser, your Flarum server handles no payment data and never holds funds.

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.

API reference (advanced)

The button uses the client-side hosted pay link, which is all most forums need. The contract is below for reference and for integrators who want the server-side tracked checkout.

Client-side hosted pay link (default, used by this extension)

GET https://pay.u.cash/embed.php

Query parameters:

Param	Required	Notes
cloud	yes	Your publishable Store Cloud Token.
amount	no	Pre-fills the amount. Omit to let the visitor pick.
currency	no	Default USD. ISO 4217 (USD, EUR) or crypto ticker.
title	no	Headline shown on the checkout.
external_reference	no	Your reference, returned in pay.u.cash reporting.
redirect	no	Where to send the visitor after payment.

This is the exact call the extension renders. No server secret is involved.

Server-side tracked checkout (optional)

If you prefer a server-created, idempotent checkout (for example to record the pending payment inside Flarum before redirecting), call this from a server route. It is idempotent per external_reference, so retries are safe:

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

function=create-transaction
&amount=<amount>
&currency_code=<USD>
&cryptocurrency_code=
&external_reference=<your unique ref>
&title=<headline>
&redirect=<return url>
&cloud=<your store cloud token>
&idempotent=1

Response (JSON):

{
  "success": true,
  "response": ["https://pay.u.cash/...", "<transactionId>", "..."]
}

The payment URL is the array element that starts with http:// or https://. Redirect the user there. Keep external_reference unique per checkout; idempotent=1 means the same reference returns the existing checkout rather than creating a duplicate.

Security model

• The Store Cloud Token is publishable. It can only create checkouts that send money to you. It cannot read balances, move funds, or access your account settings.
• No Flarum server route handles money. The default button opens pay.u.cash directly in the visitor's browser.
• For the optional server-side checkout, do not expose your account-wide credentials; use the per-store token.

License

MIT. See LICENSE.