Skip to Content
better-auth-nuvion

Hierarchy

Chain organizations into a platform, reseller and merchant tree, 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)

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.
  • A binding is created once and cannot be changed through the API. Rebinding returns an error because the organization already has one.

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.

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