Transaction lifecycle

How to poll transactions and handle each lifecycle status. The terminal flag tells you when to stop, so you don't need to work it out from the chain and RTGS fields.

Lifecycle statuses

receivedThe engine has accepted the instruction.

in-flightThe transaction is working through its steps.

settledSettlement finished successfully.

cancelledThe transaction was cancelled before it finished.

failedThe transaction ended in a failure state.

Polling

Fetch a transaction with GET /api/v1/transactions/{id}. data.terminal is the authoritative signal to stop.

curl 'https://sandbox-api.nuvante.io/api/v1/transactions/123e4567-e89b-42d3-a456-426614174000' \
  --header 'Authorization: Bearer <api-key>'

Try in sandbox

Public and diagnostic fields

Fields
Field	Type	Required	Description
lifecycleStatus	closed enum	Yes	One of received, in-flight, settled, cancelled or failed.
terminal	boolean	Yes	Stop polling automatically when this is true.
parked	boolean	Yes	True when automatic retries have run out and an operator needs to step in.
details.chain	ChainStatus	Yes	Diagnostic chain state: None, Locked, SignaturePending, Burned, Completed or ReturnedToSender.
details.rtgs	RtgsStatus	Yes	Diagnostic RTGS state, from None through the earmark, settle and cancellation stages.
details.reason	object	No	Why the transaction didn't succeed. The code is earmark_rejected, operator_cancelled or retries_exhausted.
saga.steps	array	Yes	A simple timeline using Received, Validated, Lock, Earmarked, Burning, Settled, Minting or a cancellation step.

Timing and approval SLA

Each issuer sets an approvalSlaSeconds value on its profile. It's the engine's internal time budget for polling that issuer for a final result. When the budget runs out, the engine emits a ParkedOnSilence event and parks the transaction.

Polling cadence by mode:

Mode

Typical duration

Recommended poll interval

Mode 1 (delegated signing)

Seconds to ~1 minute

5–10 s; stop when terminal: true

Mode 2 (two-phase)

Seconds to several minutes (issuer approval + RTGS)

10–30 s; use webhooks when available

Mode 3 (not yet executable)

Pending engineering design

n/a

Whatever the mode, stop polling when terminal: true. Please don't rebuild the stop condition from lifecycleStatus and the chain and RTGS fields one by one.

Transaction status and issuer events

Issuer instruction events are normalised inside the settlement engine. They explain how an issuer leg moves forward or parks. They're kept internal and don't show up as public transaction statuses.

Review issuer instruction events →