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| Import | What |
|---|---|
@umohpyro/better-auth-nuvion | The server plugin |
@umohpyro/better-auth-nuvion/client | The typed client plugin |
@umohpyro/better-auth-nuvion/engine | The 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
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 DrizzleAmounts 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:
import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";
export const { GET, POST } = toNextJsHandler(auth);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/webhookcurl -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
- Sign in, create three organizations, and call
authClient.nuvion.organization.parentto chain them. - Bind each to its own Nuvion account with
authClient.nuvion.organization.bind. - Set fee rules, then create a payment with
authClient.nuvion.payments. - Open the returned
checkoutUrland pay with the sandbox bank. Within seconds the payment moves tosplitting, thensettled.
The live example does all of this with a UI.