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
| Situation | What the plugin does |
|---|---|
| Duplicate or replayed webhook | Ignored by event id and by payment state |
| Amount differs from the quote | Not 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 5xx | Outcome unknown. The leg stays pending and the same reference is reused on retry, so it cannot pay twice |
Nuvion answers 409 for a reference | A previous attempt already created the transfer; the leg is treated as sent and waits for its webhook |
| A late event for an older attempt | Ignored |
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 does not charge for book transfers, so each leg costs exactly its amount. A leg fails only if the account holds less than that.
- 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
errorfield 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.