Skip to Content
better-auth-nuvion

Statuses

Payment statuses, leg states and kinds, and how provider errors are classified.

Payment status

pending → received → splitting → settled, with partial when a leg fails, and refund_partial → refunded for a refund.

StatusMeaningNext
pendingFunding session created, nothing receivedreceived or splitting on inflows.completed
receivedInflow confirmed, legs computedsplitting
splittingThe executor has run at least oncesettled, or partial if a leg is rejected
settledEvery split leg completedrefund_partial on refund
partialA leg failed or was rejectedsplitting after a retry
refund_partialRefund started, reversals outstandingrefunded
refundedRefund finished and every reversal completedfinal

Status changes are guarded (compare-and-set), so concurrent webhooks cannot move a payment backwards or run a step twice.

Leg state

StateMeaning
pendingNot sent, or sent with an unknown outcome (the same reference is reused on retry)
sentNuvion accepted the transfer; waiting for outflows.completed
completedNuvion confirmed it
failedDefinitively rejected; a retry uses a new reference
cancelledCancelled by a refund before it was sent

Leg kind

  • split: a parent's share, from the merchant's account to the parent's.
  • reversal: created by a refund, from a beneficiary back to the paying organization.

Provider error kinds

Each Nuvion failure is classified so the executor knows whether it is safe to retry.

KindWhenEffect on the leg
rejectedNuvion refused it definitively (4xx, for example insufficient funds or validation)failed; retry with a new reference
ambiguousTimeout, network error, 429, or 5xx; unknown whether it was createdstays pending; retry with the same reference
duplicate409: the reference already existstreated as sent; wait for its webhook

On this page