Vendure quickstart

Vendure is an open-source headless commerce platform on Node. The OpenReceive plugin adds a payment method to it: the buyer pays at the storefront’s checkout with Bitcoin over Lightning, straight into your own wallet, and Vendure places the order once the payment settles. With a swap provider, the same checkout also takes USDT, USDC, SOL and ETH, which the provider converts to BTC over Lightning into the same wallet.

Vendure keeps owning orders, prices, customers and fulfillment. The plugin keeps its payment attempts in two tables of Vendure’s own database, over Vendure’s own connection. When a payment settles, the plugin adds a settled payment to the order, with the Lightning payment hash as its transaction id, and Vendure places the order as it does for any payment method: the order reads PaymentSettled, stock is allocated and Vendure’s emails go out.

Requirements: Vendure 3.3 or later on Node 22.12 or later, with PostgreSQL, MySQL or MariaDB. SQLite and sql.js are not supported: Vendure shares their one connection with the plugin. The worker must run, with DefaultSchedulerPlugin, as a new Vendure project’s does: the plugin’s scheduled task runs there.

Install the plugin

In the Vendure server’s project:

npm install @openreceive/vendure

Add the plugin to src/vendure-config.ts, next to what is already there:

import { OpenReceivePlugin } from "@openreceive/vendure/plugin";

export const config: VendureConfig = {
  // …your existing settings
  plugins: [
    // …your existing plugins
    OpenReceivePlugin,
  ],
};

The plugin registers the payment method handler openreceive, the checkout’s routes under /openreceive on the Vendure server, a scheduled task that runs every minute on the worker, and a migration for its two tables. Restart the server and the worker. A new Vendure project runs its migrations when the server starts (runMigrations in src/index.ts), which creates the tables; if yours does not, run its migrations the way it already does.

Configure the wallet

Put the codes in the Vendure server’s .env, never in the storefront:

NWC_URI=nostr+walletconnect://…
LSC_URI_PRIMARY=lightning+swapconnect://…

NWC_URI is a receive-only Nostr Wallet Connect code: it can create invoices and read payments but cannot spend, and the plugin refuses a code that can spend. LSC_URI_PRIMARY is optional; leave it out for Bitcoin-only checkout. A new Vendure project loads .env itself (import 'dotenv/config' in vendure-config.ts). Under Docker Compose, give the server and the worker env_file: .env. Restart both after changing it.

Then create the payment method. In the dashboard, open Settings → Payment methods, create one with the code openreceive and the handler OpenReceive, and enable it. Or run, in the server’s project while the server is up:

node node_modules/@openreceive/vendure/dist/enable-openreceive.js

It signs in to the Admin API with SUPERADMIN_USERNAME and SUPERADMIN_PASSWORD from .env, as a new Vendure project has them, and creates the method in the default channel: “Bitcoin & stablecoins” with a swap code, “Bitcoin Lightning” without. Run again, it enables the method. --admin-api <url> names another Admin API and --name "…" another name. Check the codes and the wallet with:

npx openreceive doctor

doctor reads .env, prints each code as set or unset (never its value) and asks the wallet whether it is receive-only. With --url http://localhost:3000 it also checks that the plugin’s routes answer. It exits nonzero when a check fails.

Add the checkout to the storefront

The buyer pays at the checkout’s review step, before the order is placed. For Vendure’s Next.js starter, install the React checkout:

npm install @openreceive/react

Add src/app/api/openreceive/[...path]/route.ts. It forwards the checkout’s calls to the Vendure server with the buyer’s session token, which the starter keeps in its vendure-auth-token cookie, and serves the checkout’s stylesheet as it is, outside the starter’s Tailwind build:

import { readFile } from "node:fs/promises";
import { createRequire } from "node:module";
import path from "node:path";
import { NextRequest } from "next/server";
import { getAuthToken } from "@/platform/vendure/auth-token";

const SHOP_API = process.env.VENDURE_SHOP_API_URL || process.env.NEXT_PUBLIC_VENDURE_SHOP_API_URL!;
const CHANNEL =
  process.env.VENDURE_CHANNEL_TOKEN || process.env.NEXT_PUBLIC_VENDURE_CHANNEL_TOKEN || "__default_channel__";

async function stylesheet() {
  const resolve = createRequire(path.join(process.cwd(), "package.json")).resolve;
  const css = await readFile(resolve("@openreceive/react/styles.css"));
  return new Response(css, {
    headers: { "content-type": "text/css; charset=utf-8", "cache-control": "public, max-age=3600" },
  });
}

async function forward(request: NextRequest, { params }: { params: Promise<{ path: string[] }> }) {
  const { path: segments } = await params;
  if (request.method === "GET" && segments.join("/") === "styles.css") return stylesheet();
  const url = new URL(`/openreceive/${segments.join("/")}`, SHOP_API);
  url.search = request.nextUrl.search;
  const token = await getAuthToken();
  const response = await fetch(url, {
    method: request.method,
    headers: {
      "content-type": request.headers.get("content-type") ?? "application/json",
      accept: "application/json",
      "vendure-token": CHANNEL,
      ...(token ? { authorization: `Bearer ${token}` } : {}),
    },
    body: request.method === "GET" ? undefined : await request.text(),
    cache: "no-store",
  });
  const headers = new Headers({ "cache-control": "no-store" });
  for (const name of ["content-type", "retry-after", "x-request-id"]) {
    const value = response.headers.get(name);
    if (value) headers.set(name, value);
  }
  return new Response(await response.text(), { status: response.status, headers });
}

export { forward as GET, forward as POST };

Add src/features/checkout/openreceive.ts, two server actions. The first asks the plugin to start paying the active order: the plugin moves it to ArrangingPayment, as Vendure’s own checkout does before a payment, and answers the reference the checkout pays. The second runs once the payment settled, when the plugin has placed the order:

"use server";

import { updateTag } from "next/cache";
import { getLocale } from "next-intl/server";
import { redirect } from "@/platform/i18n/navigation";
import { getAuthToken } from "@/platform/vendure/auth-token";

const SHOP_API = process.env.VENDURE_SHOP_API_URL || process.env.NEXT_PUBLIC_VENDURE_SHOP_API_URL!;
const CHANNEL =
  process.env.VENDURE_CHANNEL_TOKEN || process.env.NEXT_PUBLIC_VENDURE_CHANNEL_TOKEN || "__default_channel__";

export async function startOpenReceivePayment(): Promise<{ reference: string; orderCode: string }> {
  const token = await getAuthToken();
  const response = await fetch(new URL("/openreceive/order", SHOP_API), {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "vendure-token": CHANNEL,
      ...(token ? { authorization: `Bearer ${token}` } : {}),
    },
    body: "{}",
    cache: "no-store",
  });
  const body = await response.json();
  if (!response.ok) throw new Error(body.message ?? `OpenReceive answered ${response.status}`);
  return { reference: body.reference, orderCode: body.order_code };
}

export async function finishOpenReceivePayment(orderCode: string) {
  updateTag("cart");
  updateTag("active-order");
  const locale = await getLocale();
  redirect({ href: `/order-confirmation/${orderCode}`, locale });
}

In src/features/checkout/routes/steps/review-step.tsx, show the checkout when the buyer places an order with OpenReceive:

import { finishOpenReceivePayment, startOpenReceivePayment } from "../../openreceive";
import { Checkout } from "@openreceive/react";

// The code of the OpenReceive payment method (enable-openreceive.js creates it).
const OPENRECEIVE_METHOD = "openreceive";

// in ReviewStep, beside the existing state:
const [openReceive, setOpenReceive] = useState<{ reference: string; orderCode: string } | null>(null);
const [paymentError, setPaymentError] = useState<string | null>(null);

// first in handlePlaceOrder, after setLoading(true):
if (selectedPaymentMethodCode === OPENRECEIVE_METHOD) {
  // The buyer pays here; the plugin places the order once the payment settles.
  try {
    setOpenReceive(await startOpenReceivePayment());
  } catch (error) {
    setPaymentError(error instanceof Error ? error.message : String(error));
  } finally {
    setLoading(false);
  }
  return;
}

// in place of the Place Order <Button>:
{openReceive ? (
  <>
    <link rel="stylesheet" href="/api/openreceive/styles.css" precedence="default" />
    <Checkout
      reference={openReceive.reference}
      prefix="/api/openreceive"
      resumable
      onSettled={() => {
        void finishOpenReceivePayment(openReceive.orderCode);
      }}
    />
  </>
) : (
  <Button onClick={handlePlaceOrder} /* …as it was */>…</Button>
)}
{paymentError && <p className="text-sm text-destructive text-center">{paymentError}</p>}

The order now waits in ArrangingPayment while the buyer pays. In src/features/checkout/routes/actions.ts, let transitionToArrangingPayment accept an order that is already there, so a buyer who opened the Bitcoin checkout can still pay with another method:

if (result.data.transitionOrderToState?.__typename === "OrderStateTransitionError") {
  const errorResult = result.data.transitionOrderToState;
  // The OpenReceive checkout already moved it: it is ready to pay another way.
  if (errorResult.fromState === "ArrangingPayment") return;
  throw new Error(/* …as it was */);
}

Another storefront

Where the buyer confirms the order, POST /openreceive/order on the Vendure server with the buyer’s session (the cookie or bearer token the storefront already sends Vendure, plus vendure-token on a channel other than the default) and an empty JSON body. Render React <Checkout>, or the <openreceive-checkout> element from @openreceive/elements, with the reference it answers, and send the checkout’s calls to /openreceive on the Vendure server with the same session: forward them from your storefront’s server as above, or call Vendure from the browser with a fetch that sends the session. A browser call from another site needs the storefront’s exact origin in Vendure’s apiOptions.cors.origin; a pattern or true is not enough. When the checkout reports the payment settled, the order is placed: show its confirmation.

How a payment works

  1. The buyer picks “Bitcoin & stablecoins” at the payment step and places the order. The plugin moves the order to ArrangingPayment and answers its reference: the order’s code, currency and amount due.
  2. The checkout charges that amount in the order’s currency, converted to sats at the current BTC price. Only the buyer’s session, or the signed-in customer the order belongs to, may pay it. A Shop API call cannot add an OpenReceive payment, so a buyer cannot mark an order paid.
  3. Once the wallet reports the payment, the plugin adds a settled payment to the order, and Vendure places it.
  4. The checkout takes the buyer to the order’s confirmation.

If the buyer closes the page after paying, the scheduled task finds the payment within a minute or so and places the order anyway. If the cart changes before the buyer pays, the amount due changes and so does the reference: the checkout asks for a new invoice for the new total. Vendure keeps an order in ArrangingPayment from changing; a storefront that lets the buyer go back to the cart moves it back with transitionOrderToState(state: "AddingItems").

Refunds and removal

The receive-only wallet cannot send refunds. A refund made in the dashboard stays pending in Vendure, and the plugin logs a warning naming the payment: send the refund from your own wallet, then settle the refund in the dashboard. A buyer whose swap deposit never converted reclaims it from the same checkout, with the same session, while the order is still unpaid. If you turn on swaps, keep that path available; see swap refunds.

Removing the plugin keeps its two tables: they are a record of payments received.

Tested, and not tested

Tested on 2026-10-19 with Vendure 3.8.0 on PostgreSQL 17 in Docker, its worker and the Next.js starter, a test wallet and a test swap provider: the migration, the enable script, doctor, and a guest paying an order by Lightning and by USDT on Solana in Chromium, after which the order reads PaymentSettled with the payment hash as its transaction id. A payment whose buyer left was placed by the scheduled task. Another guest, a visitor with no session, a changed amount and the Shop API’s addPaymentToOrder were refused, a reload resumed the same invoice, and a buyer who opened the Bitcoin checkout then paid with Vendure’s test method. CI runs the plugin against a Vendure 3.8 server and PostgreSQL.

Not tested: MySQL and MariaDB, more than one channel, Vendure’s other storefront starters, and a storefront calling Vendure from the browser on another site. Lightning cannot pull a payment, so OpenReceive saves no payment methods.

Next