@ucash/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 @ucash/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 '@ucash/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 '@ucash/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 '@ucash/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.