ucashpay-rust

A Rust client for U.CASH Pay. Build a hosted pay link (publishable, safe to use straight from the browser) and create a server-side tracked checkout. Non-custodial: the store Cloud token can only route incoming payments to your configured receive addresses, it cannot move funds on your behalf.

• Hosted pay link: a plain GET URL you can embed in any client.
• Server-side checkout: an idempotent (per external_reference) POST that returns a tracked payment URL and transaction id.
• Two helpers, one client, no custody.

Installation

Add it to your Cargo.toml:

[dependencies]
ucashpay = "0.1"

Or pull the latest from git:

[dependencies]
ucashpay = { git = "https://github.com/UdotCASH/ucashpay-rust" }

Usage

use ucashpay::{CheckoutOptions, HostedOptions, UcashPay};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // The store Cloud token is publishable: safe to ship in a browser or app.
    let client = UcashPay::new("st_your_store_cloud_token");

    // 1. Hosted pay link (build it anywhere, open it anywhere).
    let url = client.hosted_checkout_url(&HostedOptions {
        amount: "10.00".to_string(),
        currency: Some("USD".to_string()),
        title: Some("Pro plan".to_string()),
        external_reference: Some("order_123".to_string()),
        redirect: Some("https://example.com/thanks".to_string()),
    });
    println!("open: {url}");

    // 2. Server-side tracked checkout (call from a server route).
    let result = client
        .create_checkout(&CheckoutOptions {
            amount: "10.00".to_string(),
            currency_code: "USD".to_string(),
            title: Some("Pro plan".to_string()),
            external_reference: "order_123".to_string(),
            redirect: Some("https://example.com/thanks".to_string()),
        })
        .await?;

    println!("payment url: {}", result.payment_url);
    println!("transaction id: {}", result.transaction_id);
    Ok(())
}

Hosted pay link

hosted_checkout_url builds a GET URL against GET https://pay.u.cash/embed.php with the query params cloud, amount, currency (defaults to USD), and the optional title, external_reference, and redirect. Because it is a plain URL built from a publishable Cloud token, you can construct it in the browser, in a mobile app, or on the server.

Server-side checkout

create_checkout POSTs application/x-www-form-urlencoded to POST https://pay.u.cash/payment/ajax.php with function=create-transaction, amount, currency_code, cryptocurrency_code (empty, so pay.u.cash shows the full coin picker), external_reference, title, redirect, cloud, and idempotent=1. The response is { success: true, response: [paymentUrl, transactionId, ...] }; the client returns the array element that starts with http(s):// as payment_url and the non-URL string element as transaction_id.

The checkout is idempotent per external_reference: repeating the call with the same reference returns the same payment URL and transaction id instead of creating a duplicate.

Supported and unsupported

• Supported: one-time hosted pay links, one-time server-side checkouts, idempotency by external_reference.
• Not supported by the underlying platform: server-initiated automatic crypto recurring billing. For subscriptions, treat each cycle as a new one-time checkout and reconcile against external_reference on your end.

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

• UcashPay::new(cloud_token) -> client for https://pay.u.cash.
• UcashPay::with_base_url(cloud_token, base_url) -> client for a custom host (useful for staging).
• hosted_checkout_url(&HostedOptions) -> String.
• create_checkout(&CheckoutOptions) -> async Result<CheckoutResult, UcashPayError>.

HostedOptions: amount (required), currency, title, external_reference, redirect.

CheckoutOptions: amount (required), currency_code, title, external_reference (required), redirect.

CheckoutResult: payment_url, transaction_id.

Running the tests

cargo test

Publishing (maintainers only)

This repo ships the packaging files only and does not auto-publish. To publish a release to crates.io:

cargo login            # paste a crates.io API token once
cargo publish --dry-run # sanity check
cargo publish          # actually publish

License

MIT, see LICENSE.