ucashpay-android

Android (Kotlin) library for U.CASH Pay (pay.u.cash). Build a hosted pay link and create a tracked checkout, then launch it in a Chrome Custom Tab. Non-custodial: the library never touches user funds, and the Store Cloud Token is publishable (safe to use straight from the app or browser).

What it does

Three entry points on UcashPay:

• hostedCheckoutUrl(...) - builds the client-side hosted pay link (GET https://pay.u.cash/embed.php). The Cloud Token is publishable, so this can be assembled and launched straight from the app with no server round-trip. This is the app-first, non-custodial path.
• createCheckout(...) - calls the server-side tracked checkout endpoint (POST https://pay.u.cash/payment/ajax.php, function=create-transaction, idempotent per external_reference). Call this from a server route you control; it returns a tracked paymentUrl and transactionId.
• launchCheckout(context, url) - opens any pay.u.cash URL in a Chrome Custom Tab (with a system-browser fallback).

Install

The library is published as an Android library module (com.android.library). Until it is on Maven Central, you can use it as a source dependency:

Option A: source module

Drop the library/ module into your project and add it to settings.gradle.kts:

include(":library")
project(":library").projectDir = file("path/to/ucashpay-android/library")

Then depend on it from your app module:

dependencies {
    implementation(project(":library"))
}

Option B: JitPack (after tagging a release)

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        maven("https://jitpack.io")
    }
}

dependencies {
    implementation("com.github.UdotCASH:ucashpay-android:v0.1.0")
}

Usage

import network.ucash.ucashpay.UcashPay

// 1. Create a client with your publishable Store Cloud Token.
val pay = UcashPay.create(cloudToken = "st_your_store_cloud_token")

// --- App-first (no server needed) ---
val url = pay.hostedCheckoutUrl(
    amount = "25.00",
    currency = "USD",
    title = "Pro plan",
    externalReference = "order_123",
    redirect = "myapp://payment-complete",
)
pay.launchCheckout(context, url)

// --- Tracked checkout (call from your server, not the app) ---
// Run on a background thread:
val checkout = pay.createCheckout(
    amount = "25.00",
    currencyCode = "USD",
    title = "Pro plan",
    externalReference = "order_123",   // idempotency key
    redirect = "myapp://payment-complete",
)
// checkout.paymentUrl   -> the https://pay.u.cash/... URL to open
// checkout.transactionId -> the tracked transaction id
pay.launchCheckout(context, checkout.paymentUrl)

minSdk is 21 (Android 5.0). Dependencies: OkHttp 4.x and androidx.browser (Chrome Custom Tabs).

Important: where to call each method

• hostedCheckoutUrl(...) and launchCheckout(...) are safe to call from the app, since the Store Cloud Token is publishable.
• createCheckout(...) posts to the tracked-checkout endpoint and is idempotent per external_reference. Call it from a server route you control if you want to record the transaction server-side before redirecting the user. It is fine to call it from the app too for the non-custodial, app-only flow, but a server call gives you the transaction record.

Honest limitations

• The Store Cloud Token is publishable and safe to ship in the app, so the app-first hostedCheckoutUrl flow needs no secret. Only use a server-side route if you want to record transactions before the user pays.
• cryptocurrency_code is intentionally left empty so the buyer picks the coin on the pay.u.cash page. U.CASH Pay does not pre-select a cryptocurrency for you.
• U.CASH Pay does not custody funds. The buyer pays directly to the merchant's configured receive addresses; this library only builds the link / tracked checkout and launches it.

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.

Build

Requires Android Gradle Plugin 8.5+ and JDK 17+.

The gradle-wrapper.jar is intentionally not committed (binary). Either use a local Gradle 8.7+ install, or regenerate the wrapper once:

gradle wrapper --gradle-version 8.7

Then build and test:

./gradlew :library:assembleRelease
./gradlew :library:test

Publish (to Maven Central, manual)

This repo does not publish automatically. To release to Maven Central (via the Sonatype Portal) after tagging:

1. Configure library/build.gradle.kts with the maven-publish plugin and a publishing { ... } block that attaches sources, Javadoc, and the POM (groupId, artifactId, license, SCM, developer).
2. Sign artifacts with your GPG key and run:

./gradlew :library:publishReleasePublicationToSonatypeRepository --max-workers=1

3. Close and release the staging repository from the Sonatype Central Portal.

License

MIT. See LICENSE.