Payment lifecycle and states

The execution, settlement, and risk states of a Flow payment, what moves a flow between them, what can change before the payment is sent, and which amounts to show.

A Flow payment moves through states on three independent axes. This page describes every state, who or what moves the flow into it, what can still change, and which amounts a flow reports along the way.

​

Three axes and when a payment is done

A flow has no single status field. Instead, it reports three:

Axis	Field	Tracks
Execution	executionState	What the payer and their payment source have done
Settlement	settlementState	Delivery of the funds to your destination
Risk	riskState	The screening result for the payment source

A payment is done when settlementState is completed. A payment has failed when executionState or settlementState is failed.

Settlement starts only after execution reaches source_confirmed. Reaching source_confirmed means the payer’s funds arrived, but delivery to your destination can still be in progress or can still fail, so do not fulfill an order on source_confirmed alone.

​

Execution states

State	Meaning	Moved there by
initiated	The flow exists, and no payment source is attached yet	Your server, when it creates the flow
source_attached	The payer chose a payment source	The payer
quoted	A quote exists. For a deposit address, the address is ready to receive funds	The payer
signing	The payer is approving a wallet payment	The payer
broadcasted	The payer’s wallet sent the transaction to the network	The payer
source_detected	A deposit reached the deposit address and is being confirmed	Dynamic
source_confirmed	The payer’s funds arrived. Settlement continues on the settlement axis	Dynamic
cancelled	The flow was cancelled before the payment was sent	The payer or your server
expired	The flow reached its expiry time before the payment was sent	Dynamic
failed	The payment failed. The flow’s failure field says why	Dynamic

cancelled, expired, and failed are final. source_confirmed is final on the execution axis, and the flow continues on the settlement axis.

The states initiated, source_attached, quoted, and signing come before the payment is sent. In those states the payer can switch source, and the flow can be cancelled or can expire. Once a flow reaches broadcasted or source_detected, neither the payer nor your server can change it, and the flow ends in source_confirmed or failed.

The following diagram shows how a payment moves forward on the execution axis. Any state before the payment is sent can also move to cancelled or expired, and any state other than initiated and source_confirmed can move to failed.

​

Settlement states

State	Meaning
none	Nothing has been delivered yet. Every flow starts here
settling	The payment is being converted and delivered with a swap or bridge
completed	The funds reached your destination. The payment is done
failed	Delivery failed. Execution stays at source_confirmed, and the flow’s failure says why

A payment that needs a swap or bridge moves from none to settling and then to completed or failed. A direct wallet transfer, a deposit-address payment, and an exchange payment move from none straight to completed.

​

Risk states

State	Meaning
unknown	Screening did not return a result. The payment can continue.
cleared	The wallet passed screening, or the payer chose a source that Dynamic does not screen
blocked	The wallet was blocked by screening. The payer cannot pay from it but can choose another source

cleared on an exchange or deposit-address payment does not mean the funder was screened. A blocked result does not change the execution state, so the payer can attach a different source to the same flow. Screening explains when screening runs.

​

Paths by payment source

Payment source	Execution	Settlement
Wallet, same token and chain as a settlement	initiated → source_attached → quoted → signing → broadcasted → source_confirmed	none → completed
Wallet, conversion needed	initiated → source_attached → quoted → signing → broadcasted → source_confirmed	none → settling → completed
Deposit address	initiated → source_attached → quoted → source_detected → source_confirmed	none → completed
Exchange	initiated → source_attached → source_confirmed	none → completed

A deposit-address flow can also move from quoted straight to source_confirmed without reporting source_detected. In a withdraw flow, your platform’s wallet is the wallet source and signs the payment.

​

What can change and until when

What	Can change
Payment source	Until the payment is sent (broadcasted or source_detected). From signing, only in the payer’s current session
Amount	Only in deposit mode, when the payer requests a quote. The new amount replaces the flow’s amount, and a wallet source is screened again
Quote	The payer can request a new quote from source_attached, quoted, or signing. Each new quote replaces the previous one
Risk	Before the payment is sent. Each time the payer attaches a source, the risk state is set again for that source. It never changes after the payment is sent
Flow configuration	Never. Settlement tokens, destinations, fees, expiry, and display settings (uiConfig) are fixed when the flow is created

​

Resuming a flow

A payer can leave and come back, and how the payment resumes depends on where they come back.

When the payer attaches a source, the flow issues a session token, and the SDK stores it on the payer’s device. That token is required for every step after attaching: quoting, approving, reporting the transaction, and cancelling. Reading the flow needs only the flow ID.

• Same browser or app. The stored token is still there, so the payer resumes from the flow’s current state.
• Another device, or cleared storage. The page can read the flow, but it has no token. Before the payment is sent, the payer attaches a source again. That issues a new token on the new device, and the token on the old device stops working. After the payment is sent, nothing is left for the payer to do, and the page only shows progress.

A page that reloads while the flow is in signing cannot tell whether the payer already approved the payment in their wallet. Treat the payment as processing and keep reading the flow instead of asking the payer to approve again, because a second approval could send a second payment.

To resume correctly, read the flow and act on its current state instead of repeating the last request. A request that is not valid from the current state is rejected.

​

Amounts you will see

A flow reports three kinds of amount: what was requested, what was quoted, and what was delivered. They can differ, so show the one that matches the question the payer is asking.

Amount	Fields	Meaning
Requested	amount, currency, amountUsd, currencyTokenInfo	The amount the flow asks for. In deposit mode, the payer’s amount replaces it at quote time. currencyTokenInfo gives the symbol and decimals when the currency is SETTLEMENT_TOKEN
Quoted	quote.fromAmount, quote.toAmount, quote.fromTokenInfo, quote.toTokenInfo, quote.fees	What the payer sends and what the destination is expected to receive, in each token’s smallest unit. For a deposit address, fromAmount is the amount to send
Delivered	settlement.amount, settlement.amountUsd, settlement.toTokenInfo, settlement.toChainId, settlement.toToken, settlement.completedAt	What actually reached your destination, in the token’s smallest unit. Your server also receives it as settledAmount in the settlement webhook

​

Short payments depend on the mode

The mode decides what happens when less than the requested amount arrives.

• deposit mode accepts the smaller amount. The flow settles, and settlement.amount and settledAmount record what actually arrived. Show the payer that amount, and credit that amount, not the flow’s amount.
• payment mode does not accept it. A short deposit-address payment is not settled, and the deposit provider attempts to return it to the payer’s refund address. A short exchange payment fails. In this mode, completed means the payment was accepted in full.

A refund is never guaranteed. Failures and refunds explains how refunds are reported and what to do when one fails.

​

Limits of the delivered amount

• The settlement object is written only when settlement reaches completed. Before that, it is absent.
• settlement.amount and settledAmount are present only when the provider or the chain reports the delivered amount. Dynamic does not estimate it.
• amountUsd can be absent even when amount is present.

When the delivered amount is absent on a completed deposit flow, verify the settlement transaction (settlementTxHash) on chain before you credit an amount.

​

Observing progress

Your server learns about state changes from webhooks: one event type per axis, each with the previous and new state. Your server can also read the full flow at any time with its API token.

A payer’s page reads the flow again while it waits for the payment to move forward. The JavaScript and Flutter SDKs handle this for you. Use your server’s view, not the page’s, to decide whether to fulfill an order. Access and data explains why.

​

Next

Expiry and cancellation

How long a flow and a quote last, and who can cancel.

Failures and refunds

Failure codes, refunds, and what to show the payer.