Better Auth plugin · Nuvion

One payment, a share for every parent.

Accept Nuvion payments from your Better Auth app and split each one across your platform, resellers and merchants, with retries, refunds and signed webhooks built in.

$npm i @umohpyro/better-auth-nuvion

v0.5.0 · pre-release · Nuvion sandbox

How a payment splits

The child keeps its share. Every parent takes its cut.

A rule on an organization is what its parent takes from the money flowing through it. Fees round down, so any remainder stays with the platform and the legs always add up to the charge.

Payment · 100.00 GBP3% on the merchant · 50% of that on the reseller
Payer100.00splitMerchant97.00 GBPReseller1.50 GBPPlatform1.50 GBP
Merchantchild organization
97.00 GBP
Resellerkeeps half of the 3%
1.50 GBP
Platformroot organization
1.50 GBP

Features

Everything between the checkout and the payout.

The plugin owns the money movement, so your app only decides who gets what.

Multi-level merchants

One, two or three levels: a lone merchant, a platform, or platform, reseller and merchant. A payment cascades from the child to every parent.

Flexible fees

Flat, basis points, minimum, cap, and who bears it. Integer money; the legs always sum to the charge.

Safe by construction

Signed webhooks, de-duplication, and an idempotent executor that retries without paying twice.

Counterparties handled

The Nuvion counterparty and payment detail for each transfer are created the first time they are needed.

Retry, reconcile, refund

Re-run failed legs, check stuck payments against Nuvion, or reverse a split with reversal legs.

Typed end to end

authClient.nuvion.* is typed from the server schema, so a wrong call fails tsc.

Setup

Add it on the server, call it from the client.

Register the plugin next to the organization plugin on your server, create the typed client in your client code, then create a payment from there. Keys and secrets stay on the server.

auth.tsserver
import { betterAuth } from "better-auth";
import { organization } from "better-auth/plugins";
import { nuvion } from "@umohpyro/better-auth-nuvion";

export const auth = betterAuth({
  plugins: [
    organization(),
    nuvion({
      apiKey: process.env.NUVION_API_KEY!,
      webhookSecret: process.env.NUVION_WEBHOOK_SECRET!,
    }),
  ],
});
auth-client.tsclient
import { createAuthClient } from "better-auth/client";
import { organizationClient } from "better-auth/client/plugins";
import { nuvionClient } from "@umohpyro/better-auth-nuvion/client";

export const authClient = createAuthClient({
  plugins: [organizationClient(), nuvionClient()],
});
checkout.tsclient
import { authClient } from "./auth-client";

const { data } = await authClient.nuvion.payments({
  organizationId: merchant.id, amountMinor: 10_000, currency: "GBP",
  redirectUrl: "https://shop.example.com/done",
});
// data.checkoutUrl, data.chargedMinor, data.legs

What is verified

Tested against the real sandbox, with the limits written down.

Claims here are the ones that were run. The rest are on the status page.

Real transfersBook transfers, refunds and failed legs on the Nuvion sandbox, settled by real signed webhooks.
Real databasesPostgres, MariaDB, SQLite, Drizzle and Prisma, with 8 simultaneous deliveries producing one split.
Retries and orderingA retried webhook keeps its event id with a new signature. Out-of-order events are handled.
Honest limitsProduction, MySQL 8 on Linux and cancelled transfers are listed as not verified yet.

These docs cover the plugin only. For the Nuvion API itself, see the Nuvion API documentation. Unofficial; sandbox only.