Skip to Content
better-auth-nuvion

Introduction

Accept Nuvion payments from a Better Auth app and split each one across your platform, resellers and merchants.

better-auth-nuvion is a Better Auth plugin for Nuvion. It turns the Better Auth organization plugin into a payments hierarchy: a customer pays a merchant once through Nuvion hosted checkout, and the plugin moves each parent's share up the chain with book transfers, keeps a ledger, and can retry or refund.

Pre-release

Version 0.1, published on npm under the author's scope as @umohpyro/better-auth-nuvion while it is unofficial. Expect changes before 1.0. Status and limits lists what has been verified against the Nuvion sandbox and what has not.

What it gives you

  • Multi-level merchants. Organizations form a tree (platform, reseller, merchant; depth up to 3). A payment cascades from the child to its parents.
  • Flexible fees. Each organization has a rule for what its parent takes: a flat amount, basis points, or both, with a minimum, a cap, and a choice of who bears the fee.
  • Exact money. Integer minor units only. The legs of a split always sum to the amount charged, and rounding remainders stay with the platform.
  • Safe webhooks. HMAC-SHA256 signature check in constant time, an optional replay window, event de-duplication, and an idempotent leg executor that never pays twice.
  • Counterparties handled for you. The Nuvion counterparty and payment detail that a book transfer needs are created the first time they are needed.
  • Recovery built in. Retry failed legs, or refund a payment with reversal legs.
  • Typed client. authClient.nuvion.* is typed from the server schema.

How a payment flows

Create the checkout

Your app calls POST /nuvion/payments for the merchant organization. The plugin quotes the split, creates a Nuvion funding session, and returns a hosted checkoutUrl.

The customer pays

Nuvion collects the money into the merchant's Nuvion account and sends a signed inflows.completed webhook.

The plugin splits it

The plugin verifies the signature, matches the payment, and creates one book transfer per parent, from the merchant's account to each parent's account.

Nuvion confirms each transfer

outflows.completed events move each leg to completed, and the payment to settled. A rejected leg leaves the payment partial until you retry it.

Where to go next

About these docs

These docs cover the plugin only. For the Nuvion API itself (funding sessions, transfers, counterparties, webhooks), see the Nuvion API documentation.

On this page