ucashpay-angular

Angular components and helpers for U.CASH Pay: a Pay-with-U.CASH button plus a server-side checkout helper. Non-custodial - U.CASH never holds funds; your customer pays you directly to your own receive addresses.

• UcashPayButton - a standalone Angular component that renders an <a> styled as a button, pointing at the hosted pay.u.cash checkout.
• hostedCheckoutUrl(opts) - builds the client-side hosted pay link from a publishable store Cloud Token (safe to use straight from the browser).
• createUcashCheckout(params) - async helper for a server-side tracked checkout, idempotent per external_reference.

The store-level Cloud Token is publishable and safe to expose in the browser. It only authorizes creating checkouts that pay your store; it cannot move funds.

Install

npm install ucashpay-angular

Requires Angular 16+ (standalone components, signals) and rxjs 7.5+.

Usage

1. Client-side button (no server needed)

app.config.ts:

import { ApplicationConfig } from '@angular/core';

export const appConfig: ApplicationConfig = {
  providers: [],
};

app.component.ts:

import { Component } from '@angular/core';
import { UcashPayButton } from 'ucashpay-angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [UcashPayButton],
  template: `
    <ucash-pay-button
      [options]="payOpts"
      label="Pay with U.CASH"
    />
  `,
})
export class AppComponent {
  payOpts = {
    cloud: 'st_your_store_cloud_token',
    amount: 19.99,
    currency: 'USD',
    title: 'Pro plan',
    external_reference: 'order_123',
    redirect: 'https://example.com/thanks',
  };
}

Optional inputs:

Input	Type	Default	Description
options	HostedCheckoutOptions	(required)	Checkout options (see below).
label	string	Pay with U.CASH	Button label text.
size	'sm' | 'md' | 'lg'	'md'	Button size preset.
target	'_self' | '_blank' | ...	'_blank'	Anchor target.
rel	string	noopener noreferrer	Anchor rel.

2. Client-side hosted link (without the component)

import { hostedCheckoutUrl } from 'ucashpay-angular';

const url = hostedCheckoutUrl({
  cloud: 'st_your_store_cloud_token',
  amount: 19.99,
  currency: 'USD',           // optional, defaults to USD
  title: 'Pro plan',
  external_reference: 'order_123',
  redirect: 'https://example.com/thanks',
});
// url -> https://pay.u.cash/embed.php?cloud=...&amount=19.99&currency=USD&...

3. Server-side tracked checkout

Call createUcashCheckout() from a server route (e.g. an Express handler, an Angular serverless function, or a backend API). It is idempotent per external_reference, so it is safe to retry.

import { createUcashCheckout } from 'ucashpay-angular';

export async function handler(req, res) {
  const result = await createUcashCheckout({
    cloud: process.env.UCASH_STORE_CLOUD_TOKEN!, // keep this server-side if secret
    amount: 49.0,
    currency_code: 'USD',
    cryptocurrency_code: '',                       // empty = let payer choose
    external_reference: `order_${req.body.orderId}`,
    title: 'T-shirt',
    redirect: 'https://shop.example.com/thanks',
  });

  if (result.success && result.paymentUrl) {
    res.redirect(303, result.paymentUrl);
  } else {
    res.status(502).json({ error: result.error });
  }
}

createUcashCheckout() posts to https://pay.u.cash/payment/ajax.php with function=create-transaction and idempotent=1, then parses the JSON response { success: true, response: [paymentUrl, transactionId, ...] }, returning:

interface UcashCheckoutResult {
  success: boolean;
  paymentUrl: string | null;     // the array element starting with http(s)://
  transactionId: string | null;
  raw: unknown[];
  error?: string;
}

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

HostedCheckoutOptions

Field	Type	Required	Default	Notes
cloud	string	yes		Store Cloud Token (publishable).
amount	number | string	yes		Amount in currency.
currency	string	no	USD	Fiat currency code.
title	string	no		Checkout / item title.
external_reference	string	no		Merchant order / cart reference.
redirect	string	no		Post-payment redirect URL.

CreateCheckoutParams

Field	Type	Required	Default	Notes
cloud	string	yes		Cloud Token. Keep secret unless it is the publishable store token.
amount	number | string	yes		Amount in currency_code.
currency_code	string	no	USD	Fiat currency code.
cryptocurrency_code	string	no	''	Empty string = payer chooses the coin.
title	string	no		Checkout / item title.
external_reference	string	yes		Drives idempotency.
redirect	string	no		Post-payment redirect URL.
idempotent	boolean	no	true	Set false to disable the idempotency flag.
endpoint	string	no		Override the pay.u.cash endpoint (advanced).

Limitations

• Non-custodial. U.CASH never holds funds; payments settle directly to your receive addresses. There is no balance to withdraw from this SDK.
• No automatic crypto recurring billing. U.CASH Pay checkouts are single-charge. To model subscriptions, create a new checkout per billing cycle from your own scheduler (e.g. on an interval or webhook).
• Server-side helper requires fetch. On older Node versions, polyfill the global fetch (Node 18+ has it built in).
• Idempotency is per external_reference. Reuse the same reference to safely retry createUcashCheckout() without double-charging.

License

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