Skip to Content
better-auth-nuvion

Troubleshooting

What you see, why it happens and how to fix it, for a stuck payment, a webhook that fails, and the errors the plugin returns.

Find your symptom, check the likely causes in order. For anything that moves money, read the payment first: its status and each leg's state and error say where it stopped (Statuses).

A payment stays pending

The customer paid (or you paid in the sandbox) but the payment never changes. Almost always the plugin never received the event.

  1. No webhook is registered. Nuvion does not know where to send events. Register one at https://<your-host>/api/auth/nuvion/webhook (Webhooks).
  2. The URL is not https, or not reachable from the internet. Nuvion delivers only to https. localhost does not work: use a tunnel (Local development).
  3. The webhook is on the wrong entity. Register it on the entity that owns the account receiving the payment. In our own testing, a webhook on a parent entity did not receive the events of a payment taken on a child entity's account. Create it with that child's entity_id.
  4. The webhook was blacklisted. After repeated failed deliveries Nuvion marks it blacklisted and stops sending. Fix the cause, then create a new webhook (and put its new signing secret in NUVION_WEBHOOK_SECRET).
  5. The customer did not finish the bank step. Open the funding session in Nuvion: awaiting_user means they have not. In the sandbox the bank sign-in opens in a popup that your browser may block.
  6. The event arrived and was refused. Look at the webhook response in your logs or in Hookbox: unconfirmed-mismatch means Nuvion's record disagreed with the event (a different amount, reference or currency), and the payment is deliberately left alone.

If the payment settled at Nuvion but your app never heard, run the reconcile. A payment still pending after two minutes whose funding session settled is recovered by it (Scheduled reconcile).

Since 0.7 the reconcile also ends a payment whose checkout expired or failed at Nuvion: it becomes expired or failed, and onPaymentExpired or onPaymentFailed runs. A payment that stays pending for good usually means no reconcile is running.

The webhook answers 401

401 means the signature check failed. Check, in this order:

  • Wrong secret. NUVION_WEBHOOK_SECRET must be the whole nv_wsk_... string, from the webhook you registered for this URL. The secret is shown once, when the webhook is created. A webhook you recreated has a new secret.
  • The body was changed before the plugin saw it. The signature covers the raw bytes. A body parser, a proxy that re-encodes JSON, or middleware that reads the body first breaks it. Mount the Better Auth handler before any body parser (Recipes).
  • The clock. With webhookToleranceMs set, an event whose timestamp is further from your server's time than that is refused. Fix the server clock, or widen the window.
  • Per-tenant URLs. With /nuvion/webhook/<tenant>, an unknown tenant also answers 401.

The webhook answers 503

The plugin asked Nuvion to confirm the event and Nuvion was unreachable or answered a server error or 429. This one is meant to be retried, and Nuvion will redeliver. If it keeps happening, check your baseUrl, that the key is valid for that environment, and Nuvion's status page.

A leg is failed

A payment in partial has at least one failed share. The leg's error says why:

ErrorMeaning and fix
nuvion 400 ... on a transferNuvion refused it. The usual cause is a merchant balance too small for the share, for example after a manual payout. Add funds, then retry.
nuvion 409 ...The reference was already used. A failed transfer keeps its reference, so a retry uses a new one automatically.
the paying and receiving organizations use the same Nuvion accountTwo organizations are bound to one account. A book transfer needs somewhere else to land: bind each organization to its own account.
the receiving Nuvion account has no account number (nuvion_ban)The destination account is not fully set up in Nuvion. Check it in the dashboard.
nuvion 5xx or 429Temporary. The leg stays pending; retry or let the reconcile settle it.

Errors from the plugin's endpoints

MessageCause
unauthorized (401)No session. Sign in first.
owner/admin of the organization required (403)The caller is not an owner or admin of that organization.
organizationId is required (400)You called create payment without an organization and have no defaultOrganizationId.
payment has not been paid yet (400)You tried to refund a payment still pending.
this organization is already bound; pass replace: true ... (409)It is already linked to a Nuvion account. Pass replace: true to move it.
this organization has open payments; wait until ... (409)Changing the account is blocked while payments are open.
root organizations have no fee rule (400)A fee rule is what a parent takes from its child. The top organization has no parent.
payment not found (404)Unknown id, or one you cannot see.

Database and setup

  • relation "nuvionPayment" does not exist: the tables were not created. Run the migration with the same Better Auth version your app uses (Installation).
  • Requests from your frontend fail with a CORS or "invalid origin" error: add your site to Better Auth's trustedOrigins.
  • NUVION_API_KEY is required: the key is missing at startup. In a function-based setup, the function returned nothing for that organization.

Still stuck

Open an issue on the example repository with the payment's status, the leg errors and the webhook response, and leave keys and personal data out. Security problems go through Security instead.

On this page