Skip to Content
better-auth-nuvion

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:

StructureOrganizationsA 100.00 GBP payment to the merchant
Flat (one level)A lone merchant, no parentThe merchant keeps 100.00. No transfers, the payment settles when the money lands
Two levelsMerchant under a platform, 3% rule on the merchantMerchant 97.00, platform 3.00 (one transfer)
Three levelsMerchant under a reseller under a platform, 3% on the merchant and 50% on the resellerMerchant 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. destinations reports 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, partial or refund_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 destinations if 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

ActionWho
Set a parentowner or admin of the organization and of the new parent
Bind to Nuvionowner or admin of the organization
Set a fee ruleowner or admin of the parent organization
Create a payment, retry, refundowner 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).

On this page