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.
| Endpoint | Client method | Who |
|---|---|---|
POST /nuvion/organization/parent | nuvion.organization.parent | admin of the organization and the new parent |
POST /nuvion/organization/bind | nuvion.organization.bind | admin of the organization |
POST /nuvion/organization/destinations | nuvion.organization.destinations | admin of the organization |
POST /nuvion/fee-rule | nuvion.feeRule | admin of the parent organization |
POST /nuvion/payments | nuvion.payments | admin of the organization |
POST /nuvion/payments/retry | nuvion.payments.retry | admin of the payment's organization |
POST /nuvion/payments/refund | nuvion.payments.refund | admin of the payment's organization |
POST /nuvion/webhook | none (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" }| Field | Type | Notes |
|---|---|---|
organizationId | string | the child; its parent takes the fee |
bps | integer 0 to 10000 | default 0 |
flatMinor | integer ≥ 0 | default 0 |
minMinor, capMinor | integer ≥ 0, optional | minMinor ≤ 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.