ucashpay-nuxt

A Nuxt 3 example for U.CASH Pay: a client-side UcashPayButton component (embed link) and a server route that creates a tracked, idempotent checkout. Non-custodial - U.CASH never holds customer funds.

U.CASH Pay lets a customer pay in cryptocurrency (the customer picks the coin on the hosted checkout, or you pin one). The store Cloud token is publishable and safe to use straight from the browser, so the embed link needs no server secret.

What is in here

• components/UcashPayButton.vue - client-side "Pay with U.CASH" link. Builds the hosted checkout URL from a publishable Cloud token. No server needed.
• server/api/checkout.post.ts - server route that creates a tracked, idempotent transaction and returns the hosted payment URL plus a U.CASH transaction id.
• pages/index.vue - a demo page wiring both together.

Requirements

• Node.js 18 or newer
• A U.CASH Pay store Cloud Token (see "Set up your pay.u.cash account" below)

Install and run

npm install
npm run dev

Then open the printed local URL (default http://localhost:3000).

Usage

1. Client-side embed link (no server)

The simplest integration. Put your publishable store Cloud token straight in the component:

<template>
  <UcashPayButton
    cloud="YOUR_STORE_CLOUD_TOKEN"
    :amount="25"
    currency="USD"
    title="Order #1234"
    external-reference="order_1234"
    redirect="https://yoursite.com/thanks"
  />
</template>

This builds a link to https://pay.u.cash/embed.php?cloud=...&amount=...&currency=USD&title=...&external_reference=...&redirect=... that opens the hosted checkout in a new tab.

2. Server-side tracked checkout (idempotent)

Use the server route when you want a U.CASH transaction id recorded against an order, and when you want the call to be idempotent per external_reference (re-sending the same reference returns the existing payment instead of creating a duplicate).

const result = await $fetch('/api/checkout', {
  method: 'POST',
  body: {
    cloud: 'YOUR_STORE_CLOUD_TOKEN',
    amount: 25,
    currency_code: 'USD',
    title: 'Order #1234',
    external_reference: 'order_1234',
    redirect: 'https://yoursite.com/thanks'
  }
})

// result = { success, paymentUrl, transactionId, external_reference }

Redirect the customer to result.paymentUrl, then reconcile the order later using result.transactionId / external_reference.

The server route calls POST https://pay.u.cash/payment/ajax.php with:

function=create-transaction
amount
currency_code
cryptocurrency_code=        (empty: customer picks the coin on checkout)
external_reference
title
redirect
cloud
idempotent=1

and reads the hosted payment URL (the response array element that starts with http(s)://).

Which one should I use?

Need	Use
Fastest embed, no server	Client-side UcashPayButton
Order-linked transaction id, dedupe on retries	Server route /api/checkout

Both are non-custodial. U.CASH routes the payment directly to your own receive addresses; U.CASH never custodies the funds.

Limitations

• No automatic recurring billing. Crypto payments on U.CASH Pay are one-time charges initiated by the customer. For subscriptions, bill on your own schedule using the client-side link or server route for each cycle (the customer authorizes each payment).
• Fiat cards require your own Stripe. Connect a Stripe account under Settings -> Payment processors; that path is card acceptance on your own processor, not U.CASH custodial card processing.
• The cryptocurrency_code field is intentionally left empty here so the customer picks a coin on the hosted checkout. Pin a specific code if you want to force one.

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.