ucashpay-java

A tiny, zero-dependency Java client for U.CASH Pay. It does two things:

1. Build a hosted pay link from a publishable store Cloud Token. Safe to render straight from the browser or embed in a mobile app: no server secret required.
2. Create a server-side, tracked checkout that returns a hosted payment URL plus the U.CASH transaction id. Idempotent per external_reference, so safe to retry.

U.CASH Pay is non-custodial: U.CASH never holds merchant funds. Payments settle directly to the receive addresses you configure. The store Cloud Token is publishable: it can only route payments to your store, it cannot withdraw, transfer, or read balances.

Uses only the JDK (java.net.HttpURLConnection). Works on Java 8 and newer with no external jars.

Install

Maven

<dependency>
  <groupId>dev.ucash</groupId>
  <artifactId>ucashpay-java</artifactId>
  <version>0.1.0</version>
</dependency>

Gradle

implementation 'dev.ucash:ucashpay-java:0.1.0'

Build from source

git clone https://github.com/UdotCASH/ucashpay-java.git
cd ucashpay-java
mvn clean package

The built jar appears in target/ucashpay-java-0.1.0.jar.

Usage

import dev.ucash.CheckoutResult;
import dev.ucash.UcashPay;

import java.util.HashMap;
import java.util.Map;

public class Example {
    public static void main(String[] args) {
        UcashPay client = UcashPay.create();

        // 1) Hosted pay link (publishable Cloud Token; safe in the browser/app).
        Map<String, Object> link = new HashMap<>();
        link.put("cloud", "st_your_publishable_store_cloud_token");
        link.put("amount", "25.00");
        link.put("currency", "USD");
        link.put("title", "Pro plan");
        link.put("external_reference", "order_12345");
        link.put("redirect", "https://shop.example.com/thanks");
        String payUrl = client.hostedCheckoutUrl(link);
        System.out.println("Pay link: " + payUrl);

        // 2) Server-side tracked checkout. Call from a server route.
        Map<String, Object> checkout = new HashMap<>();
        checkout.put("cloud", "st_your_publishable_store_cloud_token");
        checkout.put("amount", "25.00");
        checkout.put("currency_code", "USD");
        checkout.put("external_reference", "order_12345");
        checkout.put("title", "Pro plan");
        checkout.put("redirect", "https://shop.example.com/thanks");
        try {
            CheckoutResult result = client.createCheckout(checkout);
            System.out.println("Payment URL:   " + result.getPaymentUrl());
            System.out.println("Transaction ID: " + result.getTransactionId());
        } catch (dev.ucash.UcashPayException e) {
            System.err.println("Checkout failed: " + e.getMessage());
        }
    }
}

Parameters

Hosted pay link (hostedCheckoutUrl)

Key	Required	Default	Notes
cloud	yes		Store Cloud Token (publishable).
amount	yes		Charge amount as a string, e.g. "25.00".
currency	no	USD	ISO 4217 currency code.
title	no		Description shown on the pay page.
external_reference	no		Your order/session id.
redirect	no		URL to return to after payment.

Server-side checkout (createCheckout)

Key	Required	Default	Notes
cloud	yes		Store Cloud Token (publishable).
amount	yes		Charge amount as a string.
external_reference	yes		Your order id. Used for idempotency (idempotent=1 sent).
currency_code	no	USD	ISO 4217 currency code.
title	no		Description shown on the pay page.
redirect	no		URL to return to after payment.

cryptocurrency_code is sent as an empty string so the customer picks the coin on the hosted page. If you want to pin a specific coin server-side, set it in the map before calling createCheckout.

Error handling

hostedCheckoutUrl only builds a URL and does not perform IO; it throws IllegalArgumentException for missing required fields. createCheckout performs an HTTP request and throws dev.ucash.UcashPayException (unchecked) on any network, HTTP, parse, or API-rejection failure.

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.

Security model

• The store Cloud Token is publishable: safe to ship in client-side code, mobile apps, or anywhere a customer could read it. It routes payments to your store but cannot move funds.
• U.CASH is non-custodial. Settlement goes to the receive addresses you configure; U.CASH never custodies merchant balances.
• Use external_reference (your order id) for idempotency. Repeating the same reference returns the original payment URL rather than creating a duplicate charge.

Limitations

• No automatic crypto recurring billing. Crypto payments are one-time, customer-initiated charges. Implement subscriptions by re-issuing a fresh checkout on each billing cycle.
• No closed/inline checkout. Both methods return a hosted payment URL on pay.u.cash; the customer completes payment there. There is no embeddable inline-confirmation surface in this client.
• Server-side checkout requires a server. createCheckout posts to the U.CASH Pay API and should be called from a server route, not directly from the browser, because it associates the charge with your external_reference and returns the tracked transaction id.

Publish to Maven Central

This repository ships the correct packaging files. To publish to Maven Central (OSSRH / Central Portal):

# 1) Configure your Sonatype Central Portal credentials + a GPG signing key
#    in ~/.m2/settings.xml (server id "central").
# 2) Install the sonatype central-publishing plugin, then:
mvn clean deploy

This step is left to the maintainer; the repo itself is not auto-published.

License

MIT. See LICENSE.