> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dynamic.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# getFlow

> Read a Flow payment by ID with the JavaScript SDK, including its states, quote, settlement data, and failure.

Reads a flow by its ID. Use it to load the payment page, to resume after a reload, and to follow the payment until it ends. `getFlow` needs no session token, so it works on any device that has the flow ID.

## Usage

```javascript theme={"system"}
import { getFlow } from '@dynamic-labs-sdk/client';

const flow = await getFlow({ flowId: 'your-flow-id' });

console.log('Execution:', flow.executionState);
console.log('Settlement:', flow.settlementState);
```

## Parameters

| Parameter | Type | Description |
| - | - | - |
| `flowId` | `string` | The flow ID. |

## Returns

`Promise<Flow>`: the flow as the payer can see it. When the flow has ended, `getFlow` also removes the flow's session token from the device, because the server no longer accepts it.

These are the fields a payment UI uses most:

| Field | Description |
| - | - |
| `id`, `mode` | The flow ID, and `payment`, `deposit`, or `withdraw`. |
| `executionState` | The payer's payment. See [Execution states](#execution-states). |
| `settlementState` | Delivery to your destination: `none`, `settling`, `completed`, or `failed`. The payment is done when it is `completed`. |
| `riskState` | Screening of the source: `unknown`, `cleared`, or `blocked`. See [Screening](https://docs.dynamic.xyz/docs/flow/screening.md#risk-states). |
| `amount`, `currency` | The requested amount, in `USD` or in the settlement token (`SETTLEMENT_TOKEN`). In `deposit` mode, the payer's chosen amount replaces it. |
| `currencyTokenInfo` | The settlement token's `symbol`, `decimals`, and optional `name` and `logoURI`, when `currency` is `SETTLEMENT_TOKEN`. |
| `amountUsd` | The amount in USD. For a token-denominated flow, priced when a quote is created, and absent before that or when no price is available. |
| `sourceType` | `wallet`, `exchange`, or `deposit_address`, once a source is attached. |
| `fromAddress`, `fromChainName`, `fromChainId`, `fromToken` | The attached source and the token being paid with. |
| `quote` | The current quote. See [`getFlowQuote`](https://docs.dynamic.xyz/docs/javascript/reference/client/get-flow-quote#returns). |
| `depositAddress` | The address the payer sends funds to, for a deposit-address source after a quote. |
| `exchangeSource` | The exchange source. `exchangeSource.metadata.url` is the purchase link. |
| `txHash` | The source transaction: the one the payer's wallet sent, or the deposit as reported by the deposit provider. Absent for exchange payments. |
| `settlement` | What was delivered. See [Settlement data](#settlement-data). |
| `failure` | Why the flow failed: `code`, `message`, `category`, `stage`, and `retryable`. See [Failures and refunds](https://docs.dynamic.xyz/docs/flow/failures-and-refunds.md). |
| `expiresAt` | When the flow expires if the payment has not been sent. |
| `uiConfig` | Display settings from your server, such as `merchantName` and `enabledPaymentMethods`. The API does not enforce them. |
| `memo` | The memo your server set when it created the flow. |

The payer's view redacts your destination addresses and omits `settlementTxHash`. Your server can read both, as described in [Access and data](https://docs.dynamic.xyz/docs/flow/security.md#what-the-payer-can-see-and-what-your-server-can-see).

## Execution states

| State | Meaning | What the payer's page does |
| - | - | - |
| `initiated` | Created, with no source attached | Attach a source. |
| `source_attached` | A source is attached | Get a quote, or wait for an exchange payment. The payer can switch source or cancel. |
| `quoted` | A quote is ready | Confirm a wallet payment, or show the deposit address. The payer can re-quote, switch source, or cancel. |
| `signing` | A wallet payment is being approved | Wait for the wallet. After a reload, show it as processing. |
| `broadcasted` | The wallet payment was sent | Show progress. |
| `source_detected` | A deposit to the deposit address was seen | Show progress. |
| `source_confirmed` | The payer's funds were received | Show progress until settlement is `completed` or `failed`. |
| `cancelled` | Cancelled before the payment was sent | Final. A new attempt needs a new flow. |
| `expired` | Expired before the payment was sent | Final. A new attempt needs a new flow. |
| `failed` | The payment failed | Final. Show `failure.message`. |

`source_confirmed` does not mean the payment is done. Keep reading the flow until `settlementState` is `completed` or `failed`. [Payment lifecycle and states](https://docs.dynamic.xyz/docs/flow/lifecycle-walkthrough.md) describes what moves a flow between states.

## Settlement data

`settlement` is written when the settlement completes. It describes what reached your destination:

| Field | Description |
| - | - |
| `toChainId` | The chain the funds were delivered on. |
| `toToken` | The token that was delivered. |
| `toAddress` | The destination address, which the payer's view redacts. |
| `amount` | The delivered amount in the token's smallest unit. Absent when the provider did not report it. |
| `amountUsd` | The delivered amount in USD, when reported. |
| `toTokenInfo` | The delivered token's `symbol` and `decimals`, when known. |
| `completedAt` | When the settlement completed. |

In `deposit` mode, a short deposit settles for what arrived, so `settlement.amount` can be smaller than the quoted amount. Use [`getFlowDeliveredAmount`](https://docs.dynamic.xyz/docs/javascript/reference/client/get-flow-delivered-amount) to read the delivered amount with its token info.

## Examples

### Follow a payment until it stops changing

[`shouldPollFlow`](https://docs.dynamic.xyz/docs/javascript/reference/client/should-poll-flow) returns `true` while the flow can still change without any action from your page.

```javascript theme={"system"}
import { getFlow, shouldPollFlow } from '@dynamic-labs-sdk/client';

const followFlow = async (flowId) => {
  let flow = await getFlow({ flowId });

  while (shouldPollFlow({ flow })) {
    await new Promise((resolve) => setTimeout(resolve, 3000));
    flow = await getFlow({ flowId });
  }

  return flow;
};
```

### Restore a flow on page load

```javascript theme={"system"}
import { FlowNotFoundError, getFlow } from '@dynamic-labs-sdk/client';

const loadFlow = async (flowId) => {
  try {
    return await getFlow({ flowId });
  } catch (error) {
    if (error instanceof FlowNotFoundError) {
      return null; // Show a "payment not found" screen
    }
    throw error;
  }
};
```

## Errors

| Error | When |
| - | - |
| `FlowNotFoundError` | The flow does not exist, or it belongs to another environment than the client's. |

[Handle Flow errors](https://docs.dynamic.xyz/docs/javascript/reference/flow-errors.md) describes every Flow error.

## React

`useGetFlow` reads the flow and refetches it every 3 seconds while `shouldPollFlow` is `true`, then stops. Do not pass your own `refetchInterval`. The hook keeps the newest flow it has seen, and does not retry errors that cannot succeed, such as `FlowNotFoundError`.

```tsx theme={"system"}
import { useGetFlow } from '@dynamic-labs-sdk/react-hooks';

function FlowStatus({ flowId }) {
  const { data: flow, isLoading } = useGetFlow({ flowId });

  if (isLoading) return <p>Loading...</p>;
  return (
    <div>
      <p>Execution: {flow?.executionState}</p>
      <p>Settlement: {flow?.settlementState}</p>
    </div>
  );
}
```

The hook stays disabled until `flowId` is defined. To run code when a state changes, use `useSubscribeToFlowStateChange` from the [React hooks catalog](https://docs.dynamic.xyz/docs/javascript/reference/react-hooks-catalog.md).

## Related

* [Build a custom payment UI](https://docs.dynamic.xyz/docs/javascript/reference/flow-ui-guide.md): route the payment page by the flow's state.
* [`shouldPollFlow`](https://docs.dynamic.xyz/docs/javascript/reference/client/should-poll-flow): decide when to read the flow again.
* [`getFlowDeliveredAmount`](https://docs.dynamic.xyz/docs/javascript/reference/client/get-flow-delivered-amount): read what a settled flow delivered.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.