Skip to Content
better-auth-nuvion

Local development

Run the plugin on your machine against the Nuvion test environment, receive real webhooks through a tunnel, and complete the sandbox bank step.

Nuvion delivers webhooks only to https addresses, and localhost is not one. To see a payment settle on your machine you need a public https URL that points at your dev server. There are two ways to do that, and a third way to skip webhooks altogether.

What you need

  • A Nuvion account in the test environment, with an approved entity and an account (Before you start).
  • A test secret key, and baseUrl: "https://api.nuvion.dev" (the default).
  • A database. SQLite is enough for development (Installation).
  • Your app running, with the Better Auth handler mounted.

Option 1: a tunnel

A tunnel gives your dev server a public https address for as long as it runs.

# Cloudflare Tunnel (no account needed for a quick tunnel)
cloudflared tunnel --url http://localhost:3000

# or ngrok
ngrok http 3000

Either prints a public address such as https://something.trycloudflare.com. Then:

  1. Register a webhook in Nuvion that points at https://<that address>/api/auth/nuvion/webhook. The signing secret is shown once, when the webhook is created.
  2. Put that secret in NUVION_WEBHOOK_SECRET and restart your app.
  3. Create a payment and pay it. The event arrives through the tunnel and the payment settles.

Quick tunnels change address every time you start them, so the webhook you registered stops working. Delete the old one and create a new one each session, or use a named tunnel with a fixed address.

Only the webhook needs the tunnel

Keep your browser on http://localhost:3000. If you also set BETTER_AUTH_URL to the tunnel address, add it to trustedOrigins, or sign-in calls from localhost will be refused.

Option 2: deploy a preview

If a tunnel is awkward, deploy the app to a host that gives you https (a preview deployment works) and register the webhook there. Use the test key and a separate database so a preview never touches production data.

Option 3: no webhook, reconcile instead

You can develop the rest of the flow without any public address. Pay the checkout, wait two minutes, then run the reconcile for the organization:

await authClient.nuvion.payments.reconcile({ organizationId });

A payment that is still pending after two minutes whose funding session settled at Nuvion is recovered, and its shares are sent (Scheduled reconcile). It is slower than a webhook, and it is also what protects you in production when a webhook is lost.

Watch the deliveries

Hookbox is a free inbox that shows every delivery with its headers, body and timing, and can check a signature for you. Register its capture URL as a second Nuvion webhook next to your own. It shows what Nuvion sent even when your app was off or answered an error. Send it test data only.

Pay in the test environment

The hosted checkout in the test environment is a sandbox:

  1. Open the checkoutUrl from the payment, press Complete Payment.
  2. Pick any bank. Banks that use OAuth open a Plaid test page.
  3. Continue, choose Go to your bank website, and finish the sign-in. This opens a popup, so allow popups for the checkout page, or the payment stays awaiting_user.
  4. The funding session becomes settled and Nuvion sends inflows.completed.

The smallest open-banking amount is 100 (£1.00). A smaller one is refused.

Reset between runs

Splits and payments are rows in your database, so deleting your dev database gives you a clean start. The Nuvion side (entities, accounts, counterparties) is not touched; the plugin reuses an existing counterparty for the same pair of accounts, and creates a new one if your database forgot it. Delete leftovers in the Nuvion dashboard when you are done.

Next

On this page