Build a payment deep link

​

Why build a custom payment deep link

• No SDK wallet connection — the app running the SDK never has to connect to the user’s wallet.
• Fewer hops — the connected-wallet path requires the user to connect the wallet and then sign a transaction, which means switching to the wallet twice. A deep link lets the user confirm and send in the wallet app once.
• Pre-filled, correct details — the deep link can carry the exact deposit address, amount, asset, and chain, so the wallet app can build a dedicated confirmation screen instead of asking the user to copy and paste values.
• Less room for error — with a raw deposit address, the user must send the exact correct amount. Any mismatch typically triggers a refund. A deep link removes most manual entry and reduces that risk.
• One code path for QR and deep links — the same URL can be rendered as a QR code on desktop, opened as a deep link on mobile web, or invoked directly from a mobile native app.

​

When to use a payment deep link

• You control the wallet app and want to keep the send UX inside it.
• The app running the SDK should not connect to the user’s wallet.
• You want one implementation that covers desktop QR codes, mobile web deep links, and mobile native deep links.
• You want to reduce the chance of the user sending the wrong amount, asset, or address.

​

How this fits into Flow

• sourceType: 'wallet' — the SDK connects a wallet and signs. This is the connected-wallet path covered in Add swap capabilities.
• sourceType: 'deposit_address' — Flow generates a unique deposit address and amount. Your extension turns that address and amount into a deep link or QR code. The wallet app sends the funds, and Flow detects the deposit and advances executionState to source_confirmed.

​

Connected wallet vs deposit deep link

​

Build the deep link

import { getDefaultClient } from "@dynamic-labs-sdk/client";
import type { DynamicClient, Flow } from "@dynamic-labs-sdk/client";
import { getCore } from "@dynamic-labs-sdk/client/core";

const APP_SCHEME = "mywallet";

export const createMyWalletDepositUrl = ({
  flow,
  returnUrl,
}: {
  flow: Flow;
  returnUrl?: string;
}): URL => {
  const url = new URL(`${APP_SCHEME}://deposit`);

  if (!flow.depositAddress) {
    throw new Error("Flow did not return a deposit address");
  }

  url.searchParams.set("flowId", flow.id);
  url.searchParams.set("depositAddress", flow.depositAddress);
  url.searchParams.set("rawAmount", flow.quote.fromAmount);

  if (flow.fromToken) {
    url.searchParams.set("fromToken", flow.fromToken);
  }

  if (flow.fromChainId) {
    url.searchParams.set("fromChainId", flow.fromChainId);
  }

  if (flow.fromChainName) {
    url.searchParams.set("fromChainName", flow.fromChainName);
  }

  if (flow.memo) {
    url.searchParams.set("memo", JSON.stringify(flow.memo));
  }

  if (returnUrl) {
    url.searchParams.set("returnUrl", returnUrl);
  }

  // Add any other fields your wallet app needs (for example, the token contract address).

  return url;
};

export const openMyWalletDeposit = (
  { flow, returnUrl }: { flow: Flow; returnUrl?: string },
  client: DynamicClient = getDefaultClient()
): Promise<void> =>
  getCore(client).openDeeplink(
    createMyWalletDepositUrl({ flow, returnUrl }).toString()
  );

• flow.depositAddress is the address the wallet must send funds to.
• flow.quote.fromAmount is the exact source amount in base units; do not fall back to flow.amount, which is the destination amount.
• fromToken, fromChainId, and fromChainName describe the asset and chain the user is paying from.
• The query parameter names and the custom scheme are up to you — this is just an example contract.

​

Use the deep link in a Flow

import {
  attachFlowSource,
  getFlowQuote,
} from "@dynamic-labs-sdk/client";
import { createMyWalletDepositUrl, openMyWalletDeposit } from "my-wallet-extension";

const flowId = "flow-abc123";

await attachFlowSource({
  flowId,
  sourceType: "deposit_address",
  fromChainId: "1",
  fromChainName: "EVM",
  // Optional: where to return funds if the transfer fails.
  refundAddress: "0x...",
});

const flow = await getFlowQuote({
  flowId,
  fromTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
});

// On mobile native or mobile web, open the wallet app directly.
await openMyWalletDeposit({
  flow,
  returnUrl: "myapp://deposit-complete",
});

// On desktop, encode the same URL as a QR code.
const qrData = createMyWalletDepositUrl({ flow }).toString();

​

QR codes vs deep links

• Desktop: show a QR code with the deposit deep-link URL. The user scans it with their phone camera or wallet app.
• Mobile web: call openDeeplink or render a button that links to the deep-link URL. A phone cannot scan a QR code that it is already displaying, so a QR code is not the primary UX on mobile web.
• Mobile native: call openDeeplink directly. If the wallet app is not installed, fall back to the QR code or an app-store prompt.

​

Development cost

• Register and handle the custom URL scheme (for example, mywallet://deposit).
• Parse the query parameters.
• Pre-fill the send screen with depositAddress, rawAmount, and the correct asset and chain.
• Validate that the amount, asset, and chain match the flow before signing.
• Optionally handle returnUrl to send the user back to the app that started the flow.

​

After the payment

​

Related

• Add swap capabilities — the connected-wallet signing path
• Open deep links
• attachFlowSource
• getFlowQuote
• getFlow