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.
Before you start: an approved Nuvion entity
The plugin splits payments between accounts that already exist. It does not create entities, collect identity documents or open accounts, because that is Nuvion's onboarding and compliance flow and the documents are personal data. In Nuvion (see its quickstart), once per entity:
- Create the entity and its person.
- Upload the KYC documents (a government ID and a proof of address) with
POST /documents. - Submit it for review with
POST /onboarding-submissions. - Wait for
status: approved, then create its accounts.
Then give each organization its entity id and account id with bind. To react when review finishes instead of polling, use the onEntityUpdated hook.
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.