Skip to Content
better-auth-nuvion

Installation

Add @umohpyro/better-auth-nuvion to a Better Auth server, create its tables, add the client, and register your webhook.

You need a Better Auth app that already uses the organization plugin, a Nuvion sandbox account with an approved entity, and one Nuvion account for every organization that will take or receive money.

Install the package

The package is published under the author's npm scope while it is unofficial: @umohpyro/better-auth-nuvion. It is one package with three entry points, in ESM and CommonJS.

npm install @umohpyro/better-auth-nuvion better-auth zod
ImportWhat
@umohpyro/better-auth-nuvionThe server plugin
@umohpyro/better-auth-nuvion/clientThe typed client plugin
@umohpyro/better-auth-nuvion/engineThe provider-agnostic split engine (fee math, hierarchy rules, ledger), usable on its own

Unofficial, pre-release

Published under the author's scope while it is unofficial. The name will change if the plugin is adopted officially, and this page will say so.

Add the plugin to your server

lib/auth.ts
import { betterAuth } from "better-auth";
import { organization } from "better-auth/plugins";
import { apiKey } from "@better-auth/api-key";
import { nuvion } from "@umohpyro/better-auth-nuvion";

export const auth = betterAuth({
  // database: ...
  plugins: [
    organization(),
    apiKey(),
    nuvion({
      apiKey: process.env.NUVION_API_KEY!,               // a sandbox key while you build
      webhookSecret: process.env.NUVION_WEBHOOK_SECRET!, // nv_wsk_..., from step 5
      baseUrl: "https://api.nuvion.dev",                 // default (sandbox)
      webhookToleranceMs: 5 * 60_000,                    // optional replay window
    }),
  ],
});

Keep keys in the environment and never commit them. See Options for every setting.

Create the tables

The plugin adds a parentOrganizationId column to organization and six nuvion* tables (schema). Use Better Auth's CLI:

npx @better-auth/cli migrate      # applies the schema
npx @better-auth/cli generate     # or generate it for Prisma and Drizzle

Amounts and timestamps are stored as bigint, so they do not overflow on Postgres.

Mount the handler and add the client

The plugin's endpoints live under your Better Auth base path, for example /api/auth/nuvion/.... In Next.js:

app/api/auth/[...all]/route.ts
import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";

export const { GET, POST } = toNextJsHandler(auth);
lib/auth-client.ts
import { createAuthClient } from "better-auth/react";
import { organizationClient } from "better-auth/client/plugins";
import { nuvionClient } from "@umohpyro/better-auth-nuvion/client";

export const authClient = createAuthClient({
  plugins: [organizationClient(), nuvionClient()],
});

Now authClient.nuvion.payments(...), .feeRule(...), .organization.parent(...) and the rest are typed. See the client reference.

Register your webhook in Nuvion

Nuvion tells your app that a customer paid by sending a webhook. Register this URL, over https, and subscribe to the inflow and outflow events:

https://your-app.example.com/api/auth/nuvion/webhook
curl -X POST https://api.nuvion.dev/entity-webhooks \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/api/auth/nuvion/webhook",
    "expires_in": 31536000,
    "enabled_events": {
      "inflows":  { "completed": true, "failed": true },
      "outflows": { "created": true, "completed": true, "failed": true, "cancelled": true, "refunded": true }
    }
  }'

The response contains a signing secret that starts with nv_wsk_. It is shown once. Put it in NUVION_WEBHOOK_SECRET. See Webhooks for how deliveries are verified and how to debug them.

Check it works

  1. Sign in, create three organizations, and call authClient.nuvion.organization.parent to chain them.
  2. Bind each to its own Nuvion account with authClient.nuvion.organization.bind.
  3. Set fee rules, then create a payment with authClient.nuvion.payments.
  4. Open the returned checkoutUrl and pay with the sandbox bank. Within seconds the payment moves to splitting, then settled.

The live example does all of this with a UI.

On this page