bubble-ucashpay

A Bubble (bubble.io) plugin that adds a U.CASH Pay element and two workflow actions for creating U.CASH Pay checkout links. Non-custodial: U.CASH never holds merchant funds, and the store Cloud token used here is publishable, so links can be built straight from the browser with no server secret.

What you get

This plugin ships three Bubble components, all driven by a publishable store Cloud token:

1. U.CASH Pay button (element): a button you drop on any page. Clicking it opens the hosted pay.u.cash checkout in the same tab or a new tab.
2. Create U.CASH Pay link (action): builds the hosted embed.php pay link as a text value you can save to a Thing, email, or redirect to. Runs server-side in Bubble, so you can compose it with any server-side workflow.
3. Create U.CASH checkout (server-side action): calls the pay.u.cash tracked checkout endpoint. Idempotent per external_reference. Returns the hosted payment URL and the transaction id.

API contract

The plugin targets two endpoints on pay.u.cash. Use them exactly as shown.

Client-side hosted pay link (publishable token, no server secret)

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

Query params:

Param	Required	Default	Notes
cloud	yes		Store Cloud Token (publishable)
amount	yes		Amount to charge, e.g. 10.00
currency	no	USD	ISO currency code
title	no		Title shown on the checkout
external_reference	no		Your order/record id
redirect	no		Where to send the buyer after payment

Server-side tracked checkout (call from a server route)

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

Body:

Param	Notes
function	create-transaction
amount	Amount to charge
currency_code	ISO currency code, default USD
cryptocurrency_code	empty string (let the payer pick)
external_reference	Your order/record id, used for idempotency
title	Checkout title
redirect	Post-payment redirect URL
cloud	Store Cloud Token
idempotent	1 (idempotent per external_reference)

Response:

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

The payment URL is the array element that starts with http:// or https://.

Install

1. Open your Bubble app and go to Plugins -> Add plugins.
2. Search for U.CASH Pay, or install from the plugin editor by pasting the plugin id (found on the plugin page in the Bubble marketplace).
3. The element appears in the visual editor under the plugin's name. The two actions appear under Workflow -> Add an event -> Plugin.

Usage

Drop-in button

1. Drag U.CASH Pay button onto your page.
2. Bind its properties:
   • Cloud token: your store Cloud Token (publishable).
   • Amount: a number or an expression like Current cell's Thing's Price.
   • Currency: USD (or leave blank for the default).
   • Title: what the buyer sees on the checkout.
   • External reference: your order id (optional).
   • Redirect URL: where the buyer lands after paying (optional).
   • Button label: defaults to "Pay with U.CASH".
   • Open in new tab: tick to open the checkout in a new tab.
3. The button builds the embed.php link entirely in the browser when clicked. No server secret is required.

Build a link in a workflow (save / email / redirect)

1. Add a server-side workflow action: Create U.CASH Pay link.
2. Fill in the same fields as above.
3. Use the returned Payment URL anywhere: save it to a Thing, send it in an email, or use it in a "Go to page" / "Open an external website" action.

Tracked checkout from a server workflow

Use Create U.CASH checkout (server-side) when you want pay.u.cash to record the transaction and hand back a stable transaction id (e.g. for reconciliation):

1. Add the action inside an API Workflow or any server-side workflow.
2. Provide a unique External reference (your order id). With idempotent=1, repeating the call with the same reference returns the same checkout instead of creating a duplicate.
3. Use the returned Payment URL and Transaction ID: redirect the buyer to the URL, and store the transaction id on your order for later reconciliation.

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.

Custody model

U.CASH Pay is non-custodial. The Cloud token used by this plugin is publishable: it identifies which store a checkout belongs to and which receive addresses funds settle to, but it cannot move funds. Buyers pay directly to the merchant's addresses; U.CASH routes and records, it does not hold balances. Keep your account-wide credentials private; only the store-level Cloud token goes in Bubble.

Repository layout

plugin.json                          # Bubble plugin manifest (element + 2 actions)
client_side/
  ucash_pay_button.js                # Element: renders the Pay button
server_side/
  create_ucash_pay_link.js           # Action: builds an embed.php link
  create_ucash_checkout.js           # Action: tracked checkout, returns URL + tx id
LICENSE                              # MIT

Local development

The plugin JS is plain ES5-compatible so the Bubble editor can load it without a build step. To sanity-check syntax locally:

node -c client_side/ucash_pay_button.js
node -c server_side/create_ucash_pay_link.js
node -c server_side/create_ucash_checkout.js

To load changes in Bubble, edit the files inside the plugin editor (or re-import this folder), then publish a new version under Plugins -> Version.

Publishing to the Bubble marketplace

This repo only contains the plugin source. To publish:

1. Open the plugin in the Bubble plugin editor.
2. Bump the version in Plugins -> Version.
3. Click Publish.

Do that from the Bubble UI; this repo does not publish on its own.

License

MIT. See LICENSE.