nopcommerce-ucashpay

U.CASH Pay payment plugin for nopCommerce (.NET).

Accept crypto and card payments through pay.u.cash. Non-custodial: every payment settles directly to the merchant's own configured receive addresses. No funds are held by the plugin, and no server-side secret is required.

How it works

1. When a customer completes checkout, nopCommerce calls the plugin's PostProcessPaymentAsync.
2. The plugin builds a U.CASH Pay hosted checkout link for the order total and redirects the customer there.
3. The customer pays with crypto (BTC, ETH, USDC, and more) or card (via the merchant's own Stripe).
4. The customer is returned to the nopCommerce order details page.
5. Settlement is non-custodial: pay.u.cash pays the merchant's configured receive addresses directly. The order starts as Pending in nopCommerce and can be reconciled to Paid via the U.CASH webhook keyed on the order GUID (external_reference).

The default flow uses the publishable embed link, which is safe to render in the browser because the store Cloud Token can only create checkouts that settle to the merchant's own receive addresses. An optional server-side checkout toggle creates an idempotent, server-tracked checkout (per order) via the pay.u.cash ajax endpoint.

Files

plugin.json                                              Plugin descriptor (copied next to the DLL)
src/Nop.Plugin.Payments.UCashPay/
  Nop.Plugin.Payments.UCashPay.csproj                    Project file (targets net6.0 and net8.0)
  UCashPayPaymentProcessor.cs                            IPaymentMethod implementation (PostProcessPayment redirect)
  UCashPayClient.cs                                      Optional server-side checkout helper (idempotent per order)
  UCashPaySettings.cs                                    Plugin settings model
  Models/ConfigurationModel.cs                           Admin configuration view model
  Controllers/UCashPayController.cs                      Admin configuration controller
  Views/Configure.cshtml                                 Admin configuration page
  Views/PaymentInfo.cshtml                               Checkout payment info block
  Views/_ViewStart.cshtml                                View start
LICENSE                                                 MIT

Build

The plugin targets net6.0 and net8.0 so it works across nopCommerce 4.60 (net6.0), 4.70 (net7.0/net8.0), and 4.80 (net8.0).

1. Install the .NET SDK that matches your nopCommerce version (6.0, 7.0, or 8.0).
2. From the project directory, build against your nopCommerce checkout so the core references resolve:

dotnet build src/Nop.Plugin.Payments.UCashPay/Nop.Plugin.Payments.UCashPay.csproj \
  -c Release \
  -p:NopCommerceRoot=/path/to/nopcommerce

NopCommerceRoot points at your nopCommerce source/output directory; the .csproj resolves Nop.Core, Nop.Data, and Nop.Services from Presentation/Nop.Web/bin/<Config>/<tfm>/.

If you build inside the nopCommerce solution (the usual case: add the .csproj to Presentation/Nop.WebFactory/Plugins/), drop the -p:NopCommerceRoot argument; the project references resolve from the solution.

Deploy into Plugins/

After a successful build, copy the output into the nopCommerce Plugins folder so the plugin manager picks it up.

For nopCommerce 4.60:

DEST=/path/to/nopcommerce/Presentation/Nop.Web/Plugins/Payments.UCashPay
mkdir -p "$DEST"
cp src/Nop.Plugin.Payments.UCashPay/bin/Release/net6.0/Nop.Plugin.Payments.UCashPay.dll "$DEST/"
cp src/Nop.Plugin.Payments.UCashPay/bin/Release/net6.0/Nop.Plugin.Payments.UCashPay.pdb "$DEST/" 2>/dev/null || true
cp plugin.json "$DEST/"
cp -R src/Nop.Plugin.Payments.UCashPay/Views "$DEST/"

For nopCommerce 4.70/4.80, substitute net8.0 for net6.0 and use the 4.70+ plugin location:

DEST=/path/to/nopcommerce/src/Plugins/Payments.UCashPay      # 4.70+ source layout
# or the published bin folder of your deployed site

Then in nopCommerce admin:

1. Restart the application (or touch web.config) so the plugin is discovered.
2. Go to Configuration -> Local plugins, find U.CASH Pay, and click Install.
3. Click Configure, paste your Store Cloud Token from pay.u.cash, and save.
4. Enable the U.CASH Pay payment method under Configuration -> Payment methods.

Usage

Once enabled, U.CASH Pay appears as a payment option at checkout. When the customer places the order they are redirected to the U.CASH Pay hosted checkout for the order total. No card or wallet data is ever entered on your nopCommerce site.

Settings

Setting	Purpose
Store Cloud Token	Store-level Cloud Token from pay.u.cash. Publishable; safe in the browser.
Checkout Title	Optional title shown on the U.CASH checkout. Defaults to the order number.
Currency Code	Optional ISO 4217 code (e.g. USD). Defaults to the order currency.
Redirect URL	Optional return URL. Defaults to the nopCommerce order details page.
Use server-side checkout	Off (default) uses the publishable embed link. On creates an idempotent, server-tracked checkout via the pay.u.cash ajax endpoint.

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 (honest)

• Recurring billing is not supported. U.CASH Pay settles push payments to your receive addresses and cannot pull funds on a schedule. nopCommerce recurring orders will surface an error if this method is selected for a recurring payment plan.
• Refunds, voids, and captures are not initiated from nopCommerce. Because settlement is non-custodial, refunds are issued directly from your pay.u.cash dashboard; the plugin surfaces a clear message in the admin for these actions.
• Order status reconciliation. The order is created as Pending on placement and paid off-server. Marking the order Paid automatically requires a small webhook receiver that maps the U.CASH webhook (keyed on external_reference = the order GUID) to a nopCommerce order status update. That receiver is intentionally out of scope of this plugin so it can be deployed wherever your nopCommerce host is reachable; see UCashPayPaymentProcessor.PostProcessPaymentAsync for the external_reference convention.
• Cards require your own Stripe. Card payments go through the merchant's own Stripe connection configured in pay.u.cash; no card data touches nopCommerce.

License

MIT. See LICENSE.