Vercel Functions recipe

For a site on Vercel with no framework: plain JavaScript functions under api/, and static HTML pages. A Vercel Function can take a Web-standard Request and return a Response, and so can @openreceive/http, so the integration is one function, one rewrite and an element on the order page. Your server code creates each Lightning invoice, the payment goes straight to your wallet, and payment attempts are stored in your Postgres database. There is no OpenReceive account, no API key and no background worker.

Optional swaps let customers pay with USDT, USDC, SOL, and ETH. A swap provider you configure converts the payment to BTC over Lightning, and it settles into the same wallet. Available assets and networks depend on the provider.

This recipe was checked on Vercel with Fluid compute, Node 24, a Neon database and @openreceive/* 0.5.0: a buyer got a real Lightning invoice, a stranger got 403, three requests at once left one live invoice, and a paid invoice marked the order paid once. The function below runs in OpenReceive’s CI on every change, through PgBouncer in transaction mode, as Neon’s pooler works.

npm install @openreceive/http @openreceive/elements pg @vercel/functions

Where it runs

The routes: one function and a rewrite

Every payment route sits under /openreceive/: /openreceive/checkouts, /openreceive/checkouts/prepare, /openreceive/payments/check, /openreceive/swaps/status and a few more. One function serves them all, through a rewrite:

{
  "rewrites": [{ "source": "/openreceive/:path*", "destination": "/api/openreceive" }],
  "functions": { "api/openreceive.js": { "maxDuration": 30 } }
}

Add both entries to vercel.json, beside any it already has. The request the function receives still carries the path the browser asked for, such as /openreceive/checkouts/prepare (Vercel appends the matched part as a path query parameter, which the routes ignore), so the handler routes it as is.

Outside Next.js, a file named api/openreceive/[...path].js is not a catch-all: it matches one path segment, so /checkouts/prepare would get Vercel’s 404 page. Use the rewrite.

maxDuration: 30 gives a request time to reach the wallet and, now and then, to scan it for payments, which OpenReceive cuts off at 9 seconds. With Fluid compute the default is already longer; without it, the Hobby plan’s default is 10 seconds.

The payment function

// lib/db.js — one small pool per function instance
import { attachDatabasePool } from "@vercel/functions";
import pg from "pg";

// Neon's pooled URL. Vercel sets DATABASE_URL in every environment.
export const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL, max: 3 });
// Closes idle connections before Vercel suspends the instance.
attachDatabasePool(pool);
// api/openreceive.js — every route under /openreceive/, through the rewrite
import { createStack } from "@openreceive/http";
import { pool } from "../lib/db.js";
import { findOrder, visitorFrom } from "../lib/orders.js"; // your own orders

let stack;

// Built on the first request, then kept for the instance's later requests.
// createStack connects to the wallet as soon as it is built, and Vercel can
// load a function well before a request arrives, so never build it at import.
function openReceive() {
  stack ??= createStack({
    wallet: { nwc: process.env.NWC_URI ?? "" },
    storage: {
      db: pool,
      // Runs once, inside the transaction that records the payment. paidAt is
      // Unix seconds: for a timestamptz column, write to_timestamp($1).
      onPaid: async ({ reference, paidAt, query }) => {
        await query(
          "UPDATE orders SET state = 'paid', paid_at = $1 WHERE id = $2 AND state = 'awaiting_payment'",
          [paidAt, reference],
        );
      },
    },
    // The price comes from the order row, never from the request.
    amountFor: async (reference) => {
      const order = await findOrder(reference);
      return order?.state === "awaiting_payment"
        ? { currency: order.currency, value: order.amount, description: order.title }
        : null;
    },
    // Only the buyer may pay for their order.
    authorize: async ({ request, resource }) => {
      const order = resource.reference ? await findOrder(resource.reference) : undefined;
      const visitor = visitorFrom(request);
      return Boolean(order && visitor && order.visitor === visitor);
    },
    // Vercel replaces any x-forwarded-for a client sends, so its first
    // address is the payer's.
    rateLimiting: {
      ip: ({ request }) => request.headers.get("x-forwarded-for")?.split(",")[0]?.trim(),
    },
  });
  return stack;
}

export function GET(request) {
  return openReceive().handler(request);
}

export function POST(request) {
  return openReceive().handler(request);
}

findOrder and visitorFrom are your own code: read the order row, and the buyer from the request’s cookie or session. The function’s exports take a Request. If your other functions use the older (req, res) form, keep them as they are: each file picks its own form.

The Next.js quickstart explains each hook. They are the same here.

A guest checkout

With no logins, give the buyer a cookie when your own code creates the order, and keep the same value on the order row. Sign it with your app’s own secret (such as SESSION_SECRET), never with NWC_URI, and make it last: a payer with a swap refund comes back hours later, and authorize must still know them (Swap refunds).

// lib/orders.js — reading the buyer back from a signed cookie
import { createHmac, timingSafeEqual } from "node:crypto";

const sign = (value) =>
  createHmac("sha256", process.env.SESSION_SECRET).update(value).digest("base64url");

export function visitorCookie(visitor) {
  return `visitor=${visitor}.${sign(visitor)}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=31536000`;
}

export function visitorFrom(request) {
  const pair = (request.headers.get("cookie") ?? "")
    .split(";")
    .map((part) => part.trim())
    .find((part) => part.startsWith("visitor="));
  const [visitor, signature] = (pair?.slice("visitor=".length) ?? "").split(".");
  if (!visitor || !signature) return undefined;
  const expected = Buffer.from(sign(visitor));
  const given = Buffer.from(signature);
  return given.length === expected.length && timingSafeEqual(given, expected) ? visitor : undefined;
}

Your database

Create OpenReceive’s two tables, openreceive_payments and openreceive_meta, with your migrations, or from the build step over the direct URL. paymentsSchemaSql is idempotent, so it can run on every deploy:

// scripts/openreceive-tables.mjs — run from "build" in package.json
import { paymentsSchemaSql } from "@openreceive/http";
import pg from "pg";

const client = new pg.Client({
  connectionString: process.env.DATABASE_URL_UNPOOLED ?? process.env.DATABASE_URL,
});
await client.connect();
try {
  await client.query(paymentsSchemaSql("postgres"));
} finally {
  await client.end();
}

Your orders stay in your own tables. OpenReceive reads the price through amountFor and marks the order paid through onPaid, and it never joins your tables.

Orders that are not in Postgres

Some sites keep orders in Stripe, Airtable, a JSON file or a KV store. The payment rows still need Postgres: add Neon for them. amountFor and onPaid can reach your orders wherever they live. In onPaid, call your order store after the database writes; query is only for SQL in the same database. Mark the order paid only once: check its state first, since onPaid runs again if your store failed the first time.

The checkout page

The page needs no bundler. @openreceive/elements ships a standalone build: copy its two files to where your site serves static files, in the same build step:

{
  "scripts": {
    "build": "node scripts/openreceive-tables.mjs && mkdir -p public/openreceive-checkout && cp node_modules/@openreceive/elements/dist/standalone/openreceive-checkout.js node_modules/@openreceive/elements/dist/standalone/openreceive-checkout.css public/openreceive-checkout/"
  }
}

Use public/ if the site serves its static files from there, and the project’s root otherwise. Then put the element on the order’s own page, with the order’s id as reference:

<link rel="stylesheet" href="/openreceive-checkout/openreceive-checkout.css" />
<script type="module" src="/openreceive-checkout/openreceive-checkout.js"></script>

<openreceive-checkout reference="ORDER_ID" prefix="/openreceive" resumable></openreceive-checkout>

A function that renders the page writes the id in. A static page can set it from its own address, such as /order.html?id=…:

<script type="module">
  const checkout = document.querySelector("openreceive-checkout");
  checkout.setAttribute("reference", new URLSearchParams(location.search).get("id"));
</script>

The payer picks Bitcoin and gets the invoice. Keep the page at the order’s own URL: a payer with a swap deposit in flight comes back to it (Swap refunds).

The way back to a swap refund

With swaps on, a deposit that arrives short or late is refunded on a later visit, often from another device. Keep the swap’s payment hash on the order row: add a swap_payment_hash TEXT column, and a function that saves it for the order’s own buyer:

// api/order-swap.js — keeps the swap's payment hash on the order
import { pool } from "../lib/db.js";
import { findOrder, visitorFrom } from "../lib/orders.js";

export async function POST(request) {
  const { reference, payment_hash: paymentHash } = await request.json();
  const order = typeof reference === "string" ? await findOrder(reference) : undefined;
  const visitor = visitorFrom(request);
  if (!order || !visitor || order.visitor !== visitor || !/^[0-9a-f]{64}$/.test(paymentHash)) {
    return new Response(null, { status: 403 });
  }
  await pool.query("UPDATE orders SET swap_payment_hash = $1 WHERE id = $2", [
    paymentHash,
    order.id,
  ]);
  return new Response(null, { status: 204 });
}

The page sends the hash when a swap starts, and writes a saved one back as resume-payment-hash, which reopens that swap instead of the payment methods:

<openreceive-checkout reference="ORDER_ID" prefix="/openreceive" resumable
  resume-payment-hash="SAVED_HASH"></openreceive-checkout>
<script type="module">
  const checkout = document.querySelector("openreceive-checkout");
  checkout.addEventListener("openreceive-state", (event) => {
    const { state } = event.detail;
    if (state.rail !== "swap" || !state.payment_hash) return;
    fetch("/api/order-swap", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ reference: checkout.getAttribute("reference"), payment_hash: state.payment_hash }),
    });
  });
</script>

Leave resume-payment-hash out while the order has none. The checkout ignores a hash the server will not serve, so a stale one does no harm.

Settings

In the project’s Settings → Environment Variables, as Secret, for Production, Preview and Development:

OpenReceive reads LSC_URI_PRIMARY and LSC_URI_BACKUP from the environment itself, so createStack takes only the wallet code. Keep them all out of vercel.json, the code and the logs. Vercel gives a deployment the variables of its environment, so a code added later reaches only the deploys after it: redeploy.

Check it

On a preview or production deploy, a stranger asking for a real order must get OpenReceive’s JSON refusal, not Vercel’s 404 page:

curl -s -X POST https://<your-deployment>/openreceive/checkouts/prepare \
  -H 'content-type: application/json' -d '{"reference":"<a real order id>"}'

It answers 403 with "code":"FORBIDDEN". Vercel’s NOT_FOUND page means the rewrite is missing. Then, as the buyer, open the order’s page: it shows the payment methods and, after you pick Bitcoin, a Lightning invoice.

A preview deployment behind Vercel Authentication answers 401 to curl. Check that one in the browser where you are signed in to Vercel, or on the production domain.

Next