U.CASH Pay for Shopify

Accept crypto (BTC, ETH, USDT, USDC, Solana, Tron, UCASH and custom tokens) and cards (via your own Stripe) on Shopify, settled direct to your wallet. Non-custodial: the app never holds funds or private keys.

This is an order pay-link app. You pick a Shopify order in the app and it mints a hosted pay.u.cash checkout link tagged to that order. When your buyer pays, pay.u.cash records the capture against the Shopify order automatically.

Why an order pay-link app (not a native checkout gateway)

Shopify does not let third-party gateways into native checkout unless you are an approved Shopify Payments Partner with a signed revenue-share agreement, and payment apps are not given the Shopify order id at all (Shopify docs: order, checkout, and line-item ids are not exposed to the Payments Apps API). That means a native payment app cannot reuse pay.u.cash's built-in capture and cannot be installed by merchants without that partnership.

The order pay-link model sidesteps all of that. It works on any Shopify plan, needs no approval, installs as an ordinary custom app, and reuses the capture that pay.u.cash already ships. If Payments Partner status is ever secured, the native path is documented in docs/PAYMENT-APP-FUTURE.md.

How it works

You open the app (logged into your store via Shopify OAuth)
  -> the app lists your orders (read_orders)
  -> you click "Create pay link" on an order
  -> the app creates a pay.u.cash checkout tagged shopify_{order.id}
  -> the app shows you the hosted checkout URL to send your buyer
Your buyer pays (crypto on-chain, or card via Stripe)
  -> pay.u.cash settles
  -> pay.u.cash's built-in Shopify capture records the payment against the order
     via the Admin REST API (POST /admin/api/.../orders/{id}/transactions.json)
  -> the Shopify order shows the captured payment

Two configuration surfaces:

1. This app (Shopify side): your pay.u.cash Store Cloud Token (so the app can create checkouts).
2. pay.u.cash admin: your Shopify Store URL and a Shopify access token with write_orders scope (so pay.u.cash can capture against your orders).

Both are required. The app only creates the tagged pay-link. pay.u.cash does the capture server-side, so this app does not need your webhook secret.

Set up your pay.u.cash account

You need a free U.CASH Pay account and a store before this app can create checkouts. Settlement is non-custodial: crypto goes straight to addresses you control.

1. Sign up at pay.u.cash with your email and password, then click the verification link in the email U.CASH Pay sends you.
2. Set your receive addresses. Go to Settings -> Addresses and enter a wallet address for each coin you want to accept. You can also use ENS, Unstoppable Domains, or FIO names instead of raw addresses. This is where crypto payments settle.
3. Create a store. Go to Account -> Stores, click + Add Store, name it (for example, after your Shopify store), and create it.
4. Copy the Store Cloud Token. In that store's row, copy the Store Cloud Token. Paste it into this app's Settings. Use the store-level token, not the account-wide one. (The webhook secret is not needed here: pay.u.cash captures against your Shopify orders server-side.)
5. Enable Shopify capture. In pay.u.cash admin open E-Commerce Integrations -> Shopify and set your Shopify Store URL and a Shopify access token (Admin API, write_orders scope). You can generate one in Shopify admin under Settings -> Apps -> Develop apps. This is what records the capture on your orders.

To also accept fiat cards, connect your own Stripe account under Settings -> Payment processors. Cards run non-custodially through Stripe.

Prerequisites

1. A pay.u.cash store with a Store Cloud Token (see above).
2. A Shopify store (any plan) where you can install a custom app.
3. A public HTTPS host for this app server (any Node.js 18+ host: a VPS, Railway, Fly.io, Render, Heroku, etc.).

Setup

1. Deploy the app server

git clone https://github.com/UdotCASH/shopify-ucashpay.git
cd shopify-ucashpay
npm install

Set environment variables:

export SHOPIFY_API_KEY="your_api_key"
export SHOPIFY_API_SECRET="your_api_secret"
export PAY_UCASH_URL="https://pay.u.cash"
export APP_URL="https://your-app-server.com"
export PORT=3000
# optional: export COOKIE_SECRET="a_long_random_string"
# optional: export DB_PATH="/var/data/ucash-shopify.json"

Run:

npm start

2. Create the Shopify app

1. Go to https://partners.shopify.com (or your Shopify admin for a custom app) and create an app named "U.CASH Pay".
2. Set the app URL to your hosted app server (APP_URL).
3. Set the redirect URI to https://YOUR_APP_SERVER_URL/auth/callback.
4. Request the read_orders scope.
5. Subscribe webhooks to https://YOUR_APP_SERVER_URL/webhooks/shopify: app/uninstalled plus the GDPR compliance topics (customers/data_request, customers/redact, shop/redact).
6. Copy the API key and API secret into the app server env vars.

3. Install on a store

Visit: https://your-app-server.com/auth?shop=your-store.myshopify.com

Approve the OAuth prompt.

4. Configure

In the app, paste your pay.u.cash Store Cloud Token and save. Make sure you have also enabled Shopify capture in pay.u.cash admin (Store URL + access token), as described in "Set up your pay.u.cash account" above.

5. Use it

Open the app, pick an order, click Create pay link, and send the link to your buyer. When they pay, the capture lands on the Shopify order.

Environment variables

Variable	Required	Default	Purpose
SHOPIFY_API_KEY	yes		Shopify app API key
SHOPIFY_API_SECRET	yes		Shopify app API secret (HMAC + session signing)
PAY_UCASH_URL	no	https://pay.u.cash	pay.u.cash base URL
APP_URL	yes	http://localhost:3000	public HTTPS URL of this app server
PORT	no	3000	listen port
COOKIE_SECRET	no	= SHOPIFY_API_SECRET	session cookie signing secret
DB_PATH	no	./data/db.json	where shop installations are stored
SHOPIFY_API_VERSION	no	2024-10	Shopify Admin REST API version

Files

• src/index.js Express app (OAuth, order list, pay-link minting, webhooks).
• src/payucash.js JS SDK (PayUCashIntegration: createCheckout + verifyWebhook).
• src/shopify.js Shopify Admin REST + OAuth/HMAC helpers.
• src/store.js dependency-free JSON persistence for shop installations.
• shopify.app.toml Shopify app config (read_orders, webhooks).
• docs/PAYMENT-APP-FUTURE.md the native Payment App path (Partner-gated).

Security

• OAuth callbacks are HMAC-verified with the API secret.
• Sessions are signed cookies (HMAC), 7-day expiry, HttpOnly + Secure + SameSite.
• Webhooks are HMAC-verified (X-Shopify-Hmac-Sha256).
• The app stores only the shop's access token, scope, and pay.u.cash Cloud token. No customer PII is persisted.
• Non-custodial: no funds or private keys ever pass through the app.

License: MIT.