getFlow - Dynamic

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

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.
`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.
`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`.
`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.
`failure`	Why the flow failed: `code`, `message`, `category`, `stage`, and `retryable`. See Failures and refunds.
`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.

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 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 to read the delivered amount with its token info.

Examples

Follow a payment until it stops changing

shouldPollFlow returns true while the flow can still change without any action from your page.

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

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 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.

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.

Build a custom payment UI: route the payment page by the flow’s state.
shouldPollFlow: decide when to read the flow again.
getFlowDeliveredAmount: read what a settled flow delivered.

​Usage

​Parameters

​Returns

​Execution states

​Settlement data

​Examples

​Follow a payment until it stops changing

​Restore a flow on page load

​Errors

​React

​Related