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 3000Either prints a public address such as https://something.trycloudflare.com. Then:
- 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. - Put that secret in
NUVION_WEBHOOK_SECRETand restart your app. - 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:
- Open the
checkoutUrlfrom the payment, press Complete Payment. - Pick any bank. Banks that use OAuth open a Plaid test page.
- 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. - The funding session becomes
settledand Nuvion sendsinflows.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
- A payment that does not move: Troubleshooting.
- Code for the common jobs: Recipes.
- Before real money: Going to production.