Skip to Content
better-auth-nuvion

Failures and retries

Why a payment can end up partial, how the leg executor avoids paying twice, and how to retry.

Nuvion has no atomic multi-recipient settlement, so each parent's share is its own book transfer (a leg). A payment can therefore be paid in, and some legs can still fail. The executor is built for that.

Failure semantics

SituationWhat the plugin does
Duplicate or replayed webhookIgnored by event id and by payment state
Amount differs from the quoteNot split
A leg is rejected (for example insufficient funds, validation)The leg becomes failed and the payment partial. A retry re-issues only that leg under a new reference
Timeout, network error, or 5xxOutcome unknown. The leg stays pending and the same reference is reused on retry, so it cannot pay twice
Nuvion answers 409 for a referenceA previous attempt already created the transfer; the leg is treated as sent and waits for its webhook
A late event for an older attemptIgnored

Every transfer's unique_reference is {legId}-a{attempt}. The attempt number only increases after a definitive rejection, which is what makes retries safe.

Retry

await authClient.nuvion.payments.retry({ paymentId });

It re-runs failed and stuck legs, leaving completed ones alone, and returns the payment status and legs. Call it from an admin action, or on a schedule for payments that stay splitting or partial. You must be an owner or admin of the payment's organization.

A stuck leg is not flagged for you

A leg left pending after an ambiguous failure keeps the payment in splitting; nothing marks it as needing attention. Watch for payments that stay in splitting, and retry them.

Common causes of a rejected leg

  • Insufficient funds. The merchant's account is credited by the checkout, then pays its parents. Nuvion also applies its own fees to the inflow and to book transfers, and the plugin does not attribute those to legs yet. A very small payment can leave too little for the last leg.
  • Same account. Two organizations bound to one account cannot pay each other. Provision ahead of time to catch it.
  • Counterparty rejected by Nuvion. The leg's error field holds the Nuvion error type.

After a successful retry

The leg's error is cleared (null) when it is re-sent or completed, so a completed leg never shows an old failure.

On this page