Skip to Content
better-auth-nuvion

Endpoints

Every endpoint the plugin adds, with request bodies, responses, and who may call it.

All endpoints are POST under your Better Auth base path (for example /api/auth), authenticated with the session cookie, except the webhook. A cookie-authenticated POST needs a valid Origin header. Roles are the Better Auth organization roles; "admin" below means owner or admin.

EndpointClient methodWho
POST /nuvion/organization/parentnuvion.organization.parentadmin of the organization and the new parent
POST /nuvion/organization/bindnuvion.organization.bindadmin of the organization
POST /nuvion/organization/destinationsnuvion.organization.destinationsadmin of the organization
POST /nuvion/fee-rulenuvion.feeRuleadmin of the parent organization
POST /nuvion/paymentsnuvion.paymentsadmin of the organization
POST /nuvion/payments/retrynuvion.payments.retryadmin of the payment's organization
POST /nuvion/payments/refundnuvion.payments.refundadmin of the payment's organization
POST /nuvion/webhooknone (Nuvion calls it)public, signature only

Set a parent

POST /nuvion/organization/parent

{ "organizationId": "org_reseller", "parentOrganizationId": "org_platform" }

parentOrganizationId may be null to detach. Response { "ok": true }. 400 for a cycle (cycle: parent is a descendant of the organization) or depth above 3 (hierarchy would exceed depth 3). 403 if you are not an admin of both organizations.

Bind to Nuvion

POST /nuvion/organization/bind

{ "organizationId": "org_merchant", "entityId": "01H...", "accountId": "01H..." }

Response { "ok": true }. An organization can be bound once.

Provision counterparties

POST /nuvion/organization/destinations

{ "organizationId": "org_merchant" }

Creates the book-transfer counterparties for the organization's splits (it to each ancestor), or reuses the saved ones.

{ "results": [
  { "toOrganizationId": "org_reseller", "status": "ready" },
  { "toOrganizationId": "org_platform", "status": "error", "message": "the paying and receiving organizations use the same Nuvion account; bind each organization to its own account" }
] }

Set a fee rule

POST /nuvion/fee-rule

{ "organizationId": "org_merchant", "bps": 300, "flatMinor": 0, "minMinor": 50, "capMinor": 5000, "bearer": "merchant" }
FieldTypeNotes
organizationIdstringthe child; its parent takes the fee
bpsinteger 0 to 10000default 0
flatMinorinteger ≥ 0default 0
minMinor, capMinorinteger ≥ 0, optionalminMinor ≤ capMinor
bearer"payer" or "merchant"default "merchant"

400 for a root organization (root organizations have no fee rule) or an invalid rule. Response { "ok": true }. Setting it again updates it.

Create a payment

POST /nuvion/payments

{ "organizationId": "org_merchant", "amountMinor": 10000, "currency": "GBP", "redirectUrl": "https://shop.example.com/done" }

amountMinor is a positive integer, currency is 3 letters, redirectUrl is a URL (https for Nuvion).

{ "paymentId": "…", "checkoutUrl": "https://app.nuvion.dev/checkout/…", "chargedMinor": 10000,
  "legs": [{ "organizationId": "org_merchant", "amountMinor": 9700 }, { "organizationId": "org_reseller", "amountMinor": 150 }, { "organizationId": "org_platform", "amountMinor": 150 }] }

Retry

POST /nuvion/payments/retry with { "paymentId": "…" }. Re-runs failed and stuck legs. Response { "paymentStatus": "splitting", "legs": [ … ] }. 404 if the payment does not exist.

Refund

POST /nuvion/payments/refund with { "paymentId": "…" }.

{ "status": "refund-started", "reversals": 2, "paymentStatus": "refund_partial", "legs": [ … ] }

400 if the payment is still pending. A second call returns { "status": "already-refunded" }.

Webhook

POST /nuvion/webhook: called by Nuvion, not by your app. Headers x-nuvion-event-id, x-nuvion-event-timestamp, x-nuvion-event-signature. 401 for a bad signature, 400 for a missing event id, otherwise 200 with a status body. See Webhooks.

Errors

Errors use Better Auth's shape, { "message": "…", "code": "…" }, with the usual HTTP statuses: 400 for validation and rule violations, 401 without a session, 403 when you are not an admin of the organization, 404 for an unknown payment.

On this page