flutter-ucashpay

A Flutter package for U.CASH Pay: a Pay with U.CASH button plus a checkout helper. Non-custodial.

• UcashPayButton widget: a one-tap button that opens the hosted U.CASH checkout.
• hostedCheckoutUrl(): builds the publishable client-side checkout link.
• createUcashCheckout(): creates a server-side tracked checkout (idempotent per external_reference).

Funds always go directly to the merchant's own configured receive addresses. The store Cloud Token is publishable and safe to embed in a client app. This package never touches, holds, or custodies funds, keys, or private data.

Install

Add the dependency in pubspec.yaml:

dependencies:
  ucashpay:
    git:
      url: https://github.com/UdotCASH/flutter-ucashpay.git

Then:

flutter pub get

Usage

1. Drop-in button (client-side)

The simplest path. The button opens the hosted checkout using only your publishable store Cloud token.

import 'package:flutter/material.dart';
import 'package:ucashpay/ucashpay.dart';

class CheckoutScreen extends StatelessWidget {
  const CheckoutScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: UcashPayButton(
          cloud: 'st_your_store_cloud_token', // publishable, safe in the app
          amount: 25.00,
          currency: 'USD',
          title: 'Pro plan',
          externalReference: 'order_12345',
          redirect: 'https://yourshop.example/thanks',
          onCheckoutComplete: () {
            // UX callback only. Reconcile on your server.
          },
          onError: (e) => debugPrint('checkout error: $e'),
        ),
      ),
    );
  }
}

2. Build the hosted URL yourself

If you want your own button or want to open the link some other way, build the URL with hostedCheckoutUrl():

import 'package:ucashpay/ucashpay.dart';
import 'package:url_launcher/url_launcher.dart';

final uri = hostedCheckoutUrl(
  cloud: 'st_your_store_cloud_token',
  amount: 25.00,
  currency: 'USD',
  title: 'Pro plan',
  externalReference: 'order_12345',
  redirect: 'https://yourshop.example/thanks',
);

await launchUrl(uri, mode: LaunchMode.externalApplication);

3. Server-side tracked checkout

For reconcilable orders, call createUcashCheckout() from a server route (e.g. a Dart backend or a Flutter app talking to your own API). It posts to https://pay.u.cash/payment/ajax.php with idempotent=1, so retrying with the same externalReference returns the same checkout.

import 'package:ucashpay/ucashpay.dart';

final result = await createUcashCheckout(
  UcashCheckoutRequest(
    cloud: 'st_your_store_cloud_token',
    amount: 25.00,
    currency: 'USD',
    title: 'Pro plan',
    externalReference: 'order_12345', // reuse the same value to reconcile
    redirect: 'https://yourshop.example/thanks',
  ),
);

print(result.paymentUrl);     // send the customer here
print(result.transactionId);  // store alongside your order

Redirect your customer to result.paymentUrl. Treat onCheckoutComplete (and any client-side signal) as a UX hint only; confirm order state on your server from the platform's webhook / your own 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.

API

Symbol	Where to call	Notes
UcashPayButton	Client	Opens hosted checkout via url_launcher. Publishable token only.
hostedCheckoutUrl(...)	Client	Builds the GET embed.php link.
createUcashCheckout(...)	Server	POST payment/ajax.php, idempotent=1. Idempotent per external_reference.

Defaults

• Endpoint: https://pay.u.cash (override via the endpoint argument).
• Currency: USD.

Limitations

• No automatic crypto recurring billing. U.CASH Pay checkouts are one-time, customer-initiated payments. To model a subscription, create a fresh checkout at the start of each billing period and reconcile on your server. This is an inherent property of non-custodial crypto payments, not a package limitation.
• No custody. This package cannot hold funds, sign transactions on behalf of a user, or sweep balances. It only constructs and opens checkout links and creates tracked checkouts.
• Reconciliation is server-side. Treat any client-side success callback as advisory. Confirm order state from the platform webhook or your own reconciliation before fulfilling an order.

Non-custodial model

The store Cloud Token is publishable: it can create checkouts and identify your store, but it cannot move funds, read balances, or access private keys. Customer cryptocurrency is settled directly to the receive addresses you configure in pay.u.cash. Nothing in this package gives the app (or its developers) custody of funds.

License

MIT. See LICENSE.