opensea-ucashpay

Wrap a U.CASH Pay checkout around an NFT mint/buy. Crypto and cards, an ETH-payment alternative. Non-custodial.

NFT marketplaces and mint dapps usually only accept ETH. With opensea-ucashpay you add a U.CASH Pay checkout button: the buyer pays the NFT price (in crypto or by card via the merchant's Stripe), and on return your dapp continues minting. Funds settle directly to the merchant's own receive addresses. No custody, no escrow, no third party holds buyer or seller funds.

mintCheckout() builds the client-side U.CASH Pay checkout link for an NFT price. The NFT id rides along as external_reference, so on return your dapp knows which NFT to resume minting.

What you get

• src/index.js: mintCheckout(opts), openCheckout(opts), readReturn(loc) - browser/client helpers.
• src/server.js: createCheckout(opts) - server-side, idempotent tracked checkout.
• index.html: a working demo page.

Install

npm install opensea-ucashpay

Client usage (browser)

The store Cloud token is publishable, so you can build and open the checkout straight from the browser.

import { mintCheckout, openCheckout, readReturn } from 'opensea-ucashpay';

// 1) Build the checkout URL for this NFT.
const url = mintCheckout({
  cloud: 'st_your_store_cloud_token',   // publishable Store Cloud Token
  amount: '25.00',                       // fiat price
  currency: 'USD',                       // default USD
  title: 'Genesis Avatar #042',
  nftId: '0xContract:42',                // becomes external_reference
  redirect: 'https://your-dapp.example/return',
});

// 2) Send the buyer to U.CASH Pay.
window.open(url, '_blank', 'noopener');
// or: openCheckout({ ... }); // opens for you

On return, read the result off the URL and resume the mint:

const status = readReturn(window.location);
if (status.paid) {
  // status.reference === '0xContract:42' (your NFT id)
  await resumeMint(status.reference);  // YOUR dapp continues the mint
}

readReturn reads status (or payment_status) and external_reference (or reference) from the query string. Treat paid === true as a signal to check your server, then trigger the on-chain mint. Verify payment on your backend before the mint transaction lands (see Server usage).

Server usage (Node 18+)

For an idempotent, tracked checkout row (recommended before you redirect), call create-transaction from a server route:

import { createCheckout } from 'opensea-ucashpay/server';

const { paymentUrl, transactionId } = await createCheckout({
  cloud: 'st_your_store_cloud_token',
  amount: '25.00',
  currency: 'USD',
  title: 'Genesis Avatar #042',
  nftId: '0xContract:42',
  redirect: 'https://your-dapp.example/return',
});

// Redirect the buyer to paymentUrl.
res.redirect(paymentUrl);

createCheckout POSTs function=create-transaction with idempotent=1, so repeated calls with the same external_reference (NFT id) return the same checkout instead of creating duplicates. The payment URL is the array element in the response that starts with http(s)://.

API

Client: src/index.js

mintCheckout(opts) -> string URL

Builds a https://pay.u.cash/embed.php?... URL.

Option	Type	Required	Default	Notes
cloud	string	yes		Store Cloud Token (publishable)
amount	number|string	yes		Fiat price to charge
currency	string	no	USD	ISO 4217 code
title	string	no	NFT Checkout	Title shown to the buyer
nftId	string	yes		NFT id, stored as external_reference
redirect	string	no		URL to return to after payment

openCheckout(opts) -> string

Calls mintCheckout and opens it in a new tab. Returns the URL.

readReturn([loc]) -> { paid, reference, raw }

Reads the U.CASH Pay return params off a URL. loc defaults to window.location.

Server: src/server.js

createCheckout(opts, [fetchImpl]) -> Promise<{ paymentUrl, transactionId, raw }>

Server-side, idempotent (per external_reference) tracked checkout. Pass fetchImpl to inject fetch if your runtime lacks a global one (Node 18+ has one).

Demo

Open index.html in a browser, paste your Store Cloud Token, and click Buy / Mint NFT with U.CASH Pay. The demo builds the checkout link with external_reference = 0xContract:42 and opens it. After payment you return to the page, which calls readReturn() and shows the status.

How it maps to your mint flow

1. Buyer picks an NFT and clicks Buy / Mint.
2. Your dapp calls mintCheckout({ nftId, amount, currency, cloud, redirect }) (or createCheckout on your server for a tracked row).
3. Buyer pays in crypto, or by card via your Stripe, on U.CASH Pay. Funds settle to your own receive addresses. Non-custodial.
4. U.CASH Pay redirects back to your redirect URL.
5. Your dapp calls readReturn(). On paid, it verifies the payment on the backend (check the U.CASH Pay transaction by external_reference) and submits the mint transaction.

Notes / limitations

• No automatic on-chain minting from payment. U.CASH Pay handles the checkout and settlement; your dapp still submits the mint transaction. Treat paid as a trigger to verify on your backend and then mint.
• One-off NFT price only. This wrapper charges a single fiat price per NFT. Recurring NFT subscriptions are out of scope (no automatic crypto recurring billing).
• Cloud token is publishable, but server-side checkout keys are not. Keep any account-wide secrets off the client. The Store Cloud Token used here is the store-level, publishable one.

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.

Publish (optional)

This repo ships the packaging files only; it does not publish to a registry. To publish to npm when you are ready:

npm version patch
npm publish --access public

License

MIT. See LICENSE.