Build a custom payment UI

import { FlowNotFoundError, getFlow, shouldPollFlow, type Flow } from "@dynamic-labs-sdk/client";

const POLL_INTERVAL_MS = 3000;

// Reads the flow, renders it, and keeps reading while it can change on its own.
// Call it on load and after every action that returns a flow.
export const watchFlow = async (flowId: string, render: (flow: Flow) => void) => {
let flow: Flow;
try {
flow = await getFlow({ flowId });
} catch (error) {
if (error instanceof FlowNotFoundError) {
showPaymentNotFound(); // Wrong flow ID, or a flow from another environment
return;
}
throw error;
}
render(flow);

while (shouldPollFlow({ flow })) {
await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
try {
flow = await getFlow({ flowId });
render(flow);
} catch {
// Keep the last flow on screen; the next read tries again
}
}
};

import { FlowNotFoundError } from "@dynamic-labs-sdk/client";
import { useGetFlow } from "@dynamic-labs-sdk/react-hooks";
import { useRef } from "react";

export const PaymentPage = ({ flowId }: { flowId: string }) => {
  // Refetches every 3 seconds while shouldPollFlow is true, and stops on its own
  const { data: flow, error } = useGetFlow({ flowId });
  const firstStateRef = useRef<string | undefined>(undefined);

  if (!flow) {
    if (error instanceof FlowNotFoundError) return <PaymentNotFound />;
    return <Loading />;
  }

  firstStateRef.current ??= flow.executionState;
  const phase = getPhase(flow, { loadedInSigning: firstStateRef.current === "signing" });

  return <PaymentScreen flow={flow} phase={phase} />;
};

import {
  attachFlowSource,
  FlowSourceBlockedError,
  getActiveNetworkId,
  type WalletAccount,
} from "@dynamic-labs-sdk/client";

export const attachWallet = async (flowId: string, walletAccount: WalletAccount) => {
  const { networkId } = await getActiveNetworkId({ walletAccount });
  try {
    const { flow } = await attachFlowSource({
      flowId,
      sourceType: "wallet",
      fromAddress: walletAccount.address,
      fromChainName: walletAccount.chain,
      fromChainId: networkId,
    });
    return flow;
  } catch (error) {
    if (error instanceof FlowSourceBlockedError) {
      // Screening blocked this wallet. Nothing was saved, so offer another wallet or source.
      showWalletBlocked();
      return undefined;
    }
    throw error;
  }
};

import { FlowSourceBlockedError, getActiveNetworkId, type WalletAccount } from "@dynamic-labs-sdk/client";
import { useAttachFlowSource } from "@dynamic-labs-sdk/react-hooks";

export const PayWithWalletButton = ({ flowId, walletAccount }: { flowId: string; walletAccount: WalletAccount }) => {
  const { mutate: attachFlowSource, error, isPending } = useAttachFlowSource();

  const attach = async () => {
    const { networkId } = await getActiveNetworkId({ walletAccount });
    attachFlowSource({
      flowId,
      sourceType: "wallet",
      fromAddress: walletAccount.address,
      fromChainName: walletAccount.chain,
      fromChainId: networkId,
    });
  };

  return (
    <>
      <button onClick={attach} disabled={isPending}>Pay with this wallet</button>
      {error instanceof FlowSourceBlockedError && <p>This wallet can't be used for this payment.</p>}
    </>
  );
};

import { getFlowQuote } from "@dynamic-labs-sdk/client";

export const quoteToken = (flowId: string, fromChainId: string, fromTokenAddress: string) =>
  getFlowQuote({ flowId, fromChainId, fromTokenAddress });

import { useGetFlowQuote } from "@dynamic-labs-sdk/react-hooks";

export const TokenOption = ({ flowId, fromChainId, token }) => {
  const { mutate: getFlowQuote, isPending } = useGetFlowQuote();

  return (
    <button
      onClick={() => getFlowQuote({ flowId, fromChainId, fromTokenAddress: token.address })}
      disabled={isPending}
    >
      {token.symbol}
    </button>
  );
};

import {
  FlowPrepareSigningError,
  getFlow,
  submitFlowTransaction,
  UserRejectedError,
  type FlowQuoteAmountCurrency,
  type WalletAccount,
} from "@dynamic-labs-sdk/client";

type SubmitParams = {
flowId: string;
walletAccount: WalletAccount;
// Deposit mode only: the amount the payer chose
amount?: string;
amountCurrency?: FlowQuoteAmountCurrency;
};

export const sendPayment = async ({ flowId, walletAccount, amount, amountCurrency }: SubmitParams) => {
  try {
    const flow = await submitFlowTransaction({
      flowId,
      walletAccount,
      amount,
      amountCurrency,
      onStepChange: (step) => showWalletPrompt(step), // "approval" or "transaction"
    });
    return { outcome: "sent", flow } as const;
  } catch (error) {
    if (error instanceof UserRejectedError) {
      // Nothing was sent, and the SDK already got a new quote. The payer can submit again.
      return { outcome: "declined" } as const;
    }
    if (error instanceof FlowPrepareSigningError && error.code === "quote_expired") {
      // Nothing was sent. Get a new quote, then let the payer confirm again.
      return { outcome: "quoteExpired" } as const;
    }
    if (error instanceof FlowPrepareSigningError && error.code === "insufficient_balance") {
      // Nothing was sent. The wallet can't cover the amount or the gas; offer another token.
      return { outcome: "insufficientBalance" } as const;
    }
    // Anything else: the payment may already be on its way. Read the flow instead of retrying.
    const flow = await getFlow({ flowId });
    return { outcome: "checkStatus", flow } as const;
  }
};

import { FlowPrepareSigningError, UserRejectedError, type WalletAccount } from "@dynamic-labs-sdk/client";
import { useSubmitFlowTransaction } from "@dynamic-labs-sdk/react-hooks";

export const ConfirmPayment = ({ flowId, walletAccount }: { flowId: string; walletAccount: WalletAccount }) => {
  const { mutate: submitFlowTransaction, error, isPending, isSuccess, reset } = useSubmitFlowTransaction();

  if (isSuccess) return null; // The flow in the useGetFlow cache moves the page to processing

  const declined = error instanceof UserRejectedError;
  const quoteExpired = error instanceof FlowPrepareSigningError && error.code === "quote_expired";
  const insufficientBalance = error instanceof FlowPrepareSigningError && error.code === "insufficient_balance";
  const canRetry = !error || declined;

  return (
    <>
      {declined && <p>Payment not approved in your wallet.</p>}
      {quoteExpired && <RefreshQuoteButton flowId={flowId} onRefreshed={reset} />}
      {insufficientBalance && <p>Not enough balance for this token. Choose another token.</p>}
      {/* Any other error: show the flow's state from useGetFlow instead of a retry button */}
      {canRetry && (
        <button onClick={() => submitFlowTransaction({ flowId, walletAccount })} disabled={isPending}>
          Confirm payment
        </button>
      )}
    </>
  );
};

import { attachFlowSource, getFlowQuote, type Chain } from "@dynamic-labs-sdk/client";

type DepositSelection = {
fromChainName: Chain; // "EVM", "SOL", "BTC", or "TRON"
fromChainId: string; // For example "8453" for Base
fromTokenAddress: string;
refundAddress: string; // The payer's address on the same chain family
};

export const startDeposit = async (flowId: string, selection: DepositSelection) => {
  await attachFlowSource({
    flowId,
    sourceType: "deposit_address",
    fromChainName: selection.fromChainName,
    fromChainId: selection.fromChainId,
    refundAddress: selection.refundAddress,
  });

return getFlowQuote({
flowId,
fromChainId: selection.fromChainId,
fromTokenAddress: selection.fromTokenAddress,
});
};

import { useAttachFlowSource, useGetFlowQuote } from "@dynamic-labs-sdk/react-hooks";

export const StartDepositButton = ({ flowId, selection }) => {
  const { mutateAsync: attachFlowSource } = useAttachFlowSource();
  const { mutateAsync: getFlowQuote, isPending } = useGetFlowQuote();

  const start = async () => {
    await attachFlowSource({
      flowId,
      sourceType: "deposit_address",
      fromChainName: selection.fromChainName,
      fromChainId: selection.fromChainId,
      refundAddress: selection.refundAddress,
    });
    await getFlowQuote({
      flowId,
      fromChainId: selection.fromChainId,
      fromTokenAddress: selection.fromTokenAddress,
    });
  };

  return <button onClick={start} disabled={isPending}>Show deposit address</button>;
};

import { getFlowSupportedExchanges } from "@dynamic-labs-sdk/client";

export const listExchanges = (flowId: string) => getFlowSupportedExchanges({ flowId });

import { useGetFlowSupportedExchanges } from "@dynamic-labs-sdk/react-hooks";

export const ExchangeList = ({ flowId, onSelect }) => {
  // Fetched once per flow
  const { data: exchanges = [] } = useGetFlowSupportedExchanges({ flowId });

  return exchanges.map((exchange) => (
    <button key={exchange.id} onClick={() => onSelect(exchange)}>
      <img src={exchange.iconUrl} alt="" width={24} height={24} />
      {exchange.label}
    </button>
  ));
};

import { attachFlowSource, FlowExchangeSourceError, type Flow, type FlowExchange } from "@dynamic-labs-sdk/client";

export const getPurchaseUrl = (flow: Flow) => {
  const metadata = flow.exchangeSource?.metadata as { url?: unknown } | undefined;
  return typeof metadata?.url === "string" ? metadata.url : undefined;
};

export const attachExchange = async (flowId: string, exchange: FlowExchange) => {
  try {
    const { flow } = await attachFlowSource({
      flowId,
      sourceType: "exchange",
      exchangeProvider: exchange.key,
    });
    return flow;
  } catch (error) {
    if (error instanceof FlowExchangeSourceError) {
      // retryable is true only for exchange_unavailable
      showExchangeUnavailable({ canRetry: error.retryable });
      return undefined;
    }
    throw error;
  }
};

import { FlowExchangeSourceError, type FlowExchange } from "@dynamic-labs-sdk/client";
import { useAttachFlowSource } from "@dynamic-labs-sdk/react-hooks";

export const PayWithExchange = ({ flowId, exchange }: { flowId: string; exchange: FlowExchange }) => {
  const { mutate: attachFlowSource, data, error, isPending } = useAttachFlowSource();
  const purchaseUrl = data ? getPurchaseUrl(data.flow) : undefined;

  if (purchaseUrl) {
    return (
      <button onClick={() => window.open(purchaseUrl, "_blank", "noopener,noreferrer")}>
        Open {exchange.label}
      </button>
    );
  }

  return (
    <>
      <button
        onClick={() => attachFlowSource({ flowId, sourceType: "exchange", exchangeProvider: exchange.key })}
        disabled={isPending}
      >
        Continue with {exchange.label}
      </button>
      {error instanceof FlowExchangeSourceError && (
        <p>{error.retryable ? "The exchange is unavailable. Try again." : "This exchange can't be used for this payment."}</p>
      )}
    </>
  );
};

import { cancelFlow, FlowSessionExpiredError, FlowStateConflictError, getFlow } from "@dynamic-labs-sdk/client";

export const cancelPayment = async (flowId: string) => {
  try {
    return await cancelFlow({ flowId });
  } catch (error) {
    if (error instanceof FlowStateConflictError || error instanceof FlowSessionExpiredError) {
      // Too late: the payment was sent, or the flow already ended. Show its real state.
      return getFlow({ flowId });
    }
    throw error;
  }
};

import { useCancelFlow } from "@dynamic-labs-sdk/react-hooks";

export const CancelButton = ({ flowId }: { flowId: string }) => {
  // On a state conflict, the hook refetches the flow so the page shows its real state
  const { mutate: cancelFlow, isPending } = useCancelFlow();

  return (
    <button onClick={() => cancelFlow({ flowId })} disabled={isPending}>
      Cancel payment
    </button>
  );
};