Skip to Content
better-auth-nuvion

How it works

The moving parts in plain words. What Nuvion holds, what the plugin does, how one payment becomes a share for every parent, and a glossary of the terms.

One payment, step by step

A customer pays a merchant £100. The merchant sits under a reseller, which sits under a platform. This is everything that happens.

  1. You ask for a checkout. Your server calls the plugin with the merchant's organization and an amount. The plugin works out the split, saves it, and asks Nuvion for a funding session. Nuvion answers with a hosted checkout address.
  2. The customer pays. They are sent to that address and pay from their bank. The money lands in the merchant's Nuvion account.
  3. Nuvion tells you. Nuvion sends a signed inflows.completed webhook to your app.
  4. The plugin checks before it acts. It verifies the signature, then asks Nuvion whether the funding session really settled for that reference, amount and currency.
  5. The shares move. For each parent the plugin asks Nuvion for a book transfer from the merchant's account to the parent's own Nuvion account. The amounts were fixed at step 1.
  6. Nuvion confirms each transfer with an outflows.completed webhook, again checked against Nuvion's own record. When every share is complete, the payment is settled and your onPaymentSettled hook runs.

If anything goes wrong in between, the payment is left in a state you can see and act on: a failed share can be retried, a lost webhook is recovered by the reconcile, and a refund moves the shares back (Failures and retries, Refunds).

What lives where

WhereWhat
NuvionThe money, the accounts, the checkout, the transfers. It is the source of truth for whether a payment really happened.
Your app and databaseYour users and organizations (Better Auth), the hierarchy and fee rules, a record of each payment and its shares.
The pluginThe logic in between: the split, the webhook receiver, the confirm step, retries and the ledger. It never holds funds.

Your server holds two secrets: a Nuvion API key (to make requests) and a webhook secret (to check that events come from Nuvion). See Security.

Glossary

Nuvion terms

TermMeaning
EntityA person or business on Nuvion. It must be reviewed and approved before it can own accounts or move money.
AccountA balance in one currency that belongs to an entity. A payment lands in an account.
Account number (nuvion_ban)The identifier a Nuvion account has for receiving a book transfer from another Nuvion account.
Funding sessionA request to collect money from a payer. For Open Banking it gives a hosted checkout address. Its status goes from awaiting_user to settled.
Book transferAn instant move between two Nuvion accounts. Nuvion does not charge for it.
Counterparty and payment detailThe recipient and how to pay them. A book transfer needs both. The plugin creates them the first time a pair of accounts needs one.
WebhookA signed message Nuvion sends to your server when something happens (a payment arrived, a transfer finished).
Unique referenceA string you choose that Nuvion keeps on a funding session or a transfer. The plugin uses it to match an event to a payment or a share.

Plugin terms

TermMeaning
OrganizationBetter Auth's tenant. In this plugin it is also a node in the payment hierarchy.
ParentThe organization above another one. A merchant's parent is its reseller (or the platform). The chain has up to three levels.
BindingThe link between an organization and its Nuvion entity and account. Each organization needs its own account.
Fee ruleWhat a parent takes from its child's payments: a percentage, a flat amount, or both, with an optional minimum and cap.
PaymentOne checkout: the amount, its status and its reference (pay_<uuid>).
LegOne share of a payment: from the merchant's account to one parent's. A split leg pays a parent. A reversal leg returns it on refund.
ReconcileAsking Nuvion about payments and legs that are still open, and settling the ones that finished while a webhook was lost.
Minor unitsAmounts as whole numbers of the smallest unit: 10_000 is £100.00.

Why a webhook is not enough

Anyone who learns your webhook address can send a request to it. The signature proves it came from Nuvion's webhook, but a body can still be wrong, late or replayed. So the plugin treats an event as a hint and Nuvion's own record as the truth (What the plugin checks before it acts).

Where to go next

On this page