Hooks, listing and reconciliation
Run code when a payment changes state, charge customers without an organization, list and reconcile payments, call from a backend with an API key, and drop in the admin view.
These are the operating tools. Each one is optional.
Hooks
Run your own code when a payment changes state. Hooks are awaited after the change is saved and fire once per change. A hook that throws is logged and ignored, so it cannot fail a webhook. A crash between the save and the call loses that call, so make hooks idempotent.
nuvion({
// ...
hooks: {
onPaymentSettled: async ({ payment, legs }) => { await grantAccess(payment.userId, payment.id); },
onPaymentPartial: async ({ payment }) => { await alertOps(payment.id); },
onLegFailed: async ({ payment, leg }) => { console.warn(leg.error); },
onRefunded: async ({ payment }) => { /* reverse what you granted */ },
onEntityUpdated: async ({ entityId, status }) => { if (status === "approved") await createAccountsAndBind(entityId); },
},
});Entity approval
onEntityUpdated runs when Nuvion says an entity's review status changed (entities.updated). That is the moment to create the entity's accounts and bind them, instead of polling GET /entities/{id}.
nuvion({
// ...
hooks: {
onEntityUpdated: async ({ entityId, status, parentEntityId, organizationIds, confirmed }) => {
if (status === "approved") await createAccountsAndBind(entityId);
if (status === "rejected" || status === "suspended") await notifyOps(entityId, status);
},
},
});| Field | Meaning |
|---|---|
entityId | The Nuvion entity |
status | incomplete, pending, approved, rejected or suspended |
parentEntityId | Its parent entity, if it has one |
organizationIds | The organizations already bound to it (empty before you bind it) |
confirmed | true when the status is what Nuvion's own record says; false only if you set confirmEvents: false |
The plugin asks Nuvion for the entity (GET /entities/{id}) before it calls the hook, and Nuvion's record wins if the event body disagrees. An entity Nuvion does not know about is ignored. The event also carries a name and a risk level; neither is passed to your hook, and nothing is stored. With per-organization keys, an entity that is not bound to an organization yet has no key to confirm with, so the hook is not called for it: use one key for onboarding, or check the entity yourself. Like the other hooks, an error in it is logged and does not fail the webhook, and it can run more than once if Nuvion redelivers, so make it idempotent.
Customers without an organization
Set defaultOrganizationId and any signed-in user can call POST /nuvion/payments without an organizationId. The payment is charged to that organization (your platform account), recorded with the payer's userId, and split by the fee rules above it, if any. Without the option, organizationId is required and the caller must administer it.
Listing and reading payments
GET /nuvion/payments/listreturns payments with their legs, newest first. WithorganizationIdit lists that organization's payments (admins only). Without it, it lists the caller's own. Optionalstatus(comma-separated),limit(at most 100) andoffset.GET /nuvion/payments/get?paymentId=returns one payment and its legs, to its payer or an admin of its organization.
const { data } = await authClient.nuvion.payments.list({ query: { organizationId, status: "partial,splitting" } });Reconciling
POST /nuvion/payments/reconcile with { organizationId } asks Nuvion for the state of every leg still sent in that organization and its descendants, and settles each one the way its webhook would. Call it from a cron. Repeating it is safe. A sent leg without a Nuvion transfer id (Nuvion answered a duplicate reference) cannot be looked up and is counted as unresolved. Nothing runs on a schedule by itself.
Scheduled reconcile
POST /nuvion/payments/reconcile needs a signed-in admin. For a scheduler, set cronSecret (at least 16 random characters) and call GET or POST /nuvion/cron/reconcile with Authorization: Bearer <cronSecret>. Without the option the endpoint does not exist.
nuvion({ /* ... */ cronSecret: process.env.CRON_SECRET! })Each run covers every organization, up to 500 open payments (the next run takes the rest), and:
- settles
sentlegs from Nuvion's own record of the transfer, as a webhook would, - recovers a payment whose checkout settled at Nuvion but whose
inflows.completednever reached you (a payment older than two minutes, so the normal webhook has had its chance), - leaves
failedlegs alone: those are retried on purpose.
It returns the counts (checked, completed, failed, pending, unresolved, errors, recovered, payments). Repeating it is safe. Any of these will run it:
{ "crons": [{ "path": "/api/auth/nuvion/cron/reconcile", "schedule": "*/10 * * * *" }] }That is Vercel Cron: set a CRON_SECRET environment variable and Vercel sends it as the bearer token. Cron frequency depends on your plan. Anywhere else:
curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://app.example.com/api/auth/nuvion/cron/reconcileA GitHub Actions schedule: workflow with that curl step works too. The secret is compared in constant time and is never logged.
Server-to-server calls (API keys)
The payment endpoints use the Better Auth session. Turn on enableSessionForAPIKeys in the apiKey plugin and a request with an x-api-key header is treated as a request by the key's owner, so a backend can charge and list without a cookie. The owner must be an admin of the organization, as for a browser session.
plugins: [organization(), apiKey({ enableSessionForAPIKeys: true }), nuvion({ /* ... */ })]Admin view
import { PaymentsAdmin } from "@umohpyro/better-auth-nuvion/react";
<PaymentsAdmin api={authClient.nuvion} organizationId={orgId} />A table of payments with leg progress, a Retry button on partial payments, and a button that runs the reconcile above. It refreshes every 15 seconds (pollMs). PaymentsTable is the same table without the fetching, for your own data loading. react is an optional peer dependency.
It carries class names and no inline styles, so you can style it with CSS variables, your own CSS or Tailwind, change every label, and add row actions. See Styling the admin view.