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.
destinationsreports 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
| 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).