unity-ucashpay

Unity SDK for U.CASH Pay: an in-app pay button and a checkout helper for Unity games and apps. Non-custodial funds always settle directly to the merchant's own configured receive addresses inside their pay.u.cash store. This SDK never touches, holds, or custodies funds.

The store Cloud Token used here is publishable: it is safe to embed in a client build or browser webview, the same way you would embed a Stripe publishable key. It can only be used to create checkouts that pay the merchant, never to withdraw.

Features

• UcashPay.HostedCheckoutUrl(options) builds a client-side hosted pay link (no network call, safe from the browser).
• UcashPay.CreateCheckout(options, cb) creates a server-side tracked checkout via UnityEngine.Networking and returns the hosted payment URL plus the transaction id. Idempotent per external_reference.
• UcashPayButton MonoBehaviour: drop it on a UI Button, set the Cloud Token in the inspector, and clicking opens the pay page.
• WebGL interop included so the pay page opens in a new browser tab in WebGL builds.

Install

Via UPM (git URL)

In Unity: Window -> Package Manager -> + -> Add package from git URL... and paste:

https://github.com/UdotCASH/unity-ucashpay.git#v0.1.0

Via UPM (local)

Clone this repo, then Package Manager -> + -> Add package from disk... and select the package.json at the repo root.

Via OpenUPM (when mirrored)

openupm add com.ucash.ucashpay

Requires Unity 2019.4 or newer.

Usage

1. In-app pay button (drop-in)

1. Add a UI Button to your canvas.
2. Attach the UcashPayButton component.
3. Fill in Cloud Token (your store token), Amount, Currency (default USD), and optionally Title, External Reference, Redirect URL.
4. Wire the Button reference (or leave it blank; the component auto-binds to a Button on the same GameObject).
5. At runtime, clicking the button opens https://pay.u.cash/embed.php?....

2. Client-side hosted link (no network call)

using Ucash.Pay;

var options = new CheckoutOptions
{
    cloud = "st_your_store_cloud_token",   // publishable
    amount = "19.99",
    currency = "USD",
    title = "Sword of Uprising",
    externalReference = "order_" + System.Guid.NewGuid(),
    redirect = "https://yourgame.example/return"
};

string payUrl = UcashPay.HostedCheckoutUrl(options);
Application.OpenURL(payUrl);

This builds:

https://pay.u.cash/embed.php?cloud=st_...&amount=19.99&currency=USD&title=...&external_reference=...&redirect=...

No server secret is required. The Cloud token is publishable and safe to ship in a client build.

3. Server-side tracked checkout (UnityWebRequest coroutine)

CreateCheckout POSTs to https://pay.u.cash/payment/ajax.php with idempotent=1 so the same externalReference never creates duplicate transactions. The Cloud token is publishable, but because this registers a transaction row it is typically called from a server route or a trusted host.

using System.Collections;
using Ucash.Pay;
using UnityEngine;

public class CheckoutDemo : MonoBehaviour
{
    public void Buy()
    {
        StartCoroutine(RunCheckout());
    }

    private IEnumerator RunCheckout()
    {
        var options = new CheckoutOptions
        {
            cloud = "st_your_store_cloud_token",
            amount = "19.99",
            currency = "USD",
            title = "Sword of Uprising",
            externalReference = "order_1234",
            redirect = "https://yourgame.example/return"
        };

        CheckoutResult result = default;
        yield return UcashPay.CreateCheckout(options, r => result = r);

        if (result.success)
        {
            Debug.Log("Pay URL: " + result.paymentUrl);
            Debug.Log("Transaction id: " + result.transactionId);
            Application.OpenURL(result.paymentUrl);
        }
        else
        {
            Debug.LogWarning("Checkout failed: " + result.error);
        }
    }
}

The response JSON is { success: true, response: [paymentUrl, transactionId, ...] }. The SDK picks the array element that starts with http(s):// as the payment URL.

API

CheckoutOptions

Field	Required	Notes
cloud	yes	Store Cloud Token. Publishable.
amount	yes	Fiat amount as a string, e.g. "10.50".
currency	no	Defaults to "USD".
title	no	Shown on the pay page.
externalReference	no	Your order id. Reuse to deduplicate a tracked checkout.
redirect	no	URL the user lands on after paying.

CheckoutResult

Field	Meaning
success	true when the API responded success.
paymentUrl	Hosted payment URL to present to the user.
transactionId	pay.u.cash transaction id, when present.
response	Raw response payload (for debugging).
error	Human-readable error when success is false.
httpStatus	HTTP status code from the request.

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.

Limitations (documented honestly)

• No automatic crypto recurring billing. U.CASH Pay checkouts are one-time payments initiated by the user. Unity-side auto-recurring billing is not supported by the protocol today. If you need subscriptions, gate them on your own server by re-issuing a new CreateCheckout per cycle and let the user approve each one.
• CreateCheckout is a network call. Use it from a coroutine on a MonoBehaviour. The hosted HostedCheckoutUrl path is a pure string build with no network dependency and is the recommended client-side path.
• JsonUtility cannot map a heterogeneous top-level array, so the SDK scans the response for the first http(s):// element as the payment URL. This matches the documented response shape but is intentionally defensive.

Security model

• Non-custodial. Funds settle directly to the merchant's receive addresses configured in pay.u.cash.
• The Cloud token is publishable (safe in the browser / client build). It can only create checkouts that pay the merchant.
• The merchant's payout keys, wallet secrets, and account-wide credentials are never exposed to or required by this SDK.

License

MIT. See LICENSE.