ucashpay-elixir

Elixir client for U.CASH Pay: build a hosted pay link and create a tracked, server-side checkout. Non-custodial.

Two entry points:

• Ucashpay.hosted_checkout_url/1 - builds a publishable, browser-safe pay link from the store Cloud Token. No network call.
• Ucashpay.create_checkout/1 - performs an idempotent server-side POST to create a tracked payment. Call this from a server route.

The library has zero required dependencies. It uses the built-in :inets httpc by default and will use Finch automatically if you add it as an optional dependency.

Installation

Add ucashpay to your list of dependencies in mix.exs:

def deps do
  [
    {:ucashpay, "~> 0.1.0"}
  ]
end

If you want to use Finch as the HTTP client (recommended for high-throughput applications), add it explicitly:

def deps do
  [
    {:ucashpay, "~> 0.1.0"},
    {:finch, "~> 0.16"}
  ]
end

Then run:

mix deps.get

Usage

Hosted pay link (browser-safe)

The Cloud Token is publishable and safe to expose in the browser/app. This function is pure and makes no network request.

url = Ucashpay.hosted_checkout_url(
  cloud: "st_your_store_cloud_token",
  amount: 25.00,
  currency: "USD",            # optional, defaults to "USD"
  title: "Pro plan",
  external_reference: "order_123",
  redirect: "https://shop.example.com/return"
)

# Redirect or render `url` in an iframe / link in the browser.

Tracked checkout (server-side)

Call this from a server route. The request is idempotent per external_reference: repeated calls with the same reference return the same checkout instead of creating duplicates.

case Ucashpay.create_checkout(
  cloud: "st_your_store_cloud_token",
  amount: 25.00,
  title: "Pro plan",
  external_reference: "order_123",
  redirect: "https://shop.example.com/return"
) do
  {:ok, %{payment_url: url, transaction_id: id}} ->
    # Redirect the customer to `url`, or render it.
    IO.puts("Send the customer to: #{url} (txn #{id})")

  {:error, reason} ->
    IO.inspect(reason, label: "checkout failed")
end

create_checkout/1 returns:

• {:ok, %{payment_url: binary, transaction_id: binary | nil, raw: map}} on success. payment_url is the element of the API response that starts with http:// or https://.
• {:error, term} on failure (network error, non-200 status, or API error).

Options

Option	hosted_checkout_url/1	create_checkout/1	Description
:cloud	required	required	Store Cloud Token (publishable)
:amount	required	required	Charge amount (number or string)
:currency / :currency_code	optional (USD)	optional (USD)	ISO 4217 currency code
:title	optional	optional	Charge description
:external_reference	optional	recommended	Your order/reference id (idempotency key)
:redirect	optional	optional	Return URL after payment

For create_checkout/1, :currency is accepted as an alias for :currency_code.

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.

Non-custodial model

U.CASH Pay is non-custodial: payouts go straight to the receive addresses you configure in your pay.u.cash account. The store Cloud Token is publishable and is safe to embed in a client app or browser; it can only be used to create checkouts that credit your configured addresses. It cannot move funds out of your account.

create_checkout/1 is still best called from a server route so you can record the external_reference against your own order book before redirecting the customer.

Publishing to Hex (maintainers)

This repo only contains packaging files. To publish a release to Hex:

mix hex.publish

You will need a Hex account and to have run mix hex.user auth first. Do not publish from this repo automatically.

License

MIT. See LICENSE.