Hierarchy
Use one, two or three levels of organizations (a lone merchant, a platform, or platform, reseller and merchant), and bind each one to its own Nuvion account.
The plugin builds on the Better Auth organization plugin. It adds one pointer, parentOrganizationId, so organizations form a tree. A payment made to a leaf organization (the merchant) is split with every ancestor up to the root (the platform).
Platform depth 1 (root)
└─ Reseller depth 2
└─ Merchant depth 3 (leaf: the customer pays this one)Choosing a structure
The tree is data, not a fixed shape. Use as many levels as your business has, from one to three:
| Structure | Organizations | A 100.00 GBP payment to the merchant |
|---|---|---|
| Flat (one level) | A lone merchant, no parent | The merchant keeps 100.00. No transfers, the payment settles when the money lands |
| Two levels | Merchant under a platform, 3% rule on the merchant | Merchant 97.00, platform 3.00 (one transfer) |
| Three levels | Merchant under a reseller under a platform, 3% on the merchant and 50% on the reseller | Merchant 97.00, reseller 1.50, platform 1.50 (two transfers) |
- Many merchants, one platform is two levels: give each merchant the same parent. Siblings never affect each other.
- A merchant has one parent. The structure is a tree, not a graph, so a merchant cannot sit under two platforms.
- Three levels is the ceiling. A fourth level is rejected when you set the parent, and again when a payment is quoted.
- A flat organization has no fee rule (a rule is what the parent takes), and an organization with a parent but no rule passes nothing up.
- Every organization on the chain still needs its own Nuvion account (see below), including the platform in a two-level setup.
You can change the structure later with organization.parent. The split is fixed when the payment is created: its legs are saved at checkout, so changing a parent or a rule while a customer is paying does not change what that payment pays out. New payments use the new structure. (A payment created before 0.3, or by a lone organization, has no saved legs and is worked out when the money lands.)
Set a parent
await authClient.nuvion.organization.parent({
organizationId: reseller.id,
parentOrganizationId: platform.id, // or null to detach
});The call is rejected with 400 when:
- it would create a cycle (an organization cannot be placed under its own descendant, or itself),
- the tree would be deeper than 3 levels, counting the subtree below the organization you are moving.
You must be an owner or admin of the organization and of the new parent.
Bind each organization to Nuvion
Tell the plugin which Nuvion entity and account an organization uses:
await authClient.nuvion.organization.bind({
organizationId: merchant.id,
entityId: "01H...", // the Nuvion entity that owns the account
accountId: "01H...", // the account that is credited and that pays out shares
});- Payments for the organization are created on that entity, and its checkout credits that account.
- Its shares move out of that account by book transfer.
- Every organization needs a different account. A book transfer needs another account to land in, so two organizations on the same account cannot pay each other.
destinationsreports this before a customer pays. - Binding an organization that already has an account is refused unless you pass
replace: true. See Changing an account.
Entities and accounts
All organizations can live under the entity your API key belongs to, each with its own account, or you can use child entities. A parent key can act on a direct child entity.
Changing an account
await authClient.nuvion.organization.bind({ organizationId: merchant.id, entityId: "01H...", accountId: "01H...", replace: true });- It is refused (
409) while the organization has open payments (pending,received,splitting,partialorrefund_partial): they were checked out to the old account and would split from the new one. Wait until they settle or are refunded. - Passing the same entity and account again changes nothing.
- The saved counterparties that point at the old account number, in both directions, are forgotten. The next transfer creates them again, so run
destinationsif you want to check the new account before a customer pays. - Legs already sent are not affected, and unpaid payments keep their saved split.
Who can do what
| Action | Who |
|---|---|
| Set a parent | owner or admin of the organization and of the new parent |
| Bind to Nuvion | owner or admin of the organization |
| Set a fee rule | owner or admin of the parent organization |
| Create a payment, retry, refund | owner or admin of the payment's organization |
Roles come from the Better Auth organization plugin. Calls use the signed-in session, so a cookie-authenticated POST from a browser needs a valid Origin header (Better Auth's CSRF check).