通过 Plaid 关联银行账户

使用以下操作让用户通过 Plaid Link 将银行账户连接到 Fluz。关联是所有银行账户资金功能的入口：一旦账户连接，您就可以读取其余额和可用支出额度、拉取其交易历史，并在连接后来断开时进行修复——每项功能都在各自的页面中介绍。 Transactional Graph Service (TGS) 提供了一个公开的 GraphQL 封装来对接 Fluz 的 Plaid 集成。identity-service 仍是 Plaid 令牌、银行账户接入、余额、历史交易以及 Plaid webhook 的权威记录系统。TGS 永远不会向您的应用返回 Plaid 访问令牌或公用令牌。

认证

使用包含 MANAGE_PAYMENT 范围的 Fluz 用户 Bearer 访问令牌 调用 /api/v1/graphql。 Plaid 字段不支持 Basic 认证。请先通过标准的 TGS 认证流程获取用户访问令牌，然后使用以下方式调用这些字段：

Authorization: Bearer <fluz-user-access-token>

关联流程速览

创建 Link 令牌（createPlaidLinkToken）。
使用该令牌打开 Plaid Link。
在 Plaid 的 onSuccess 中，将返回的 public_token 发送回 TGS（completePlaidLink）。
存储完成响应中的 platformItemId——这是后续用于重新关联的安全公共标识符。

1. 创建 Link 令牌

mutation CreatePlaidLinkToken($input: CreatePlaidLinkTokenInput!) {
  createPlaidLinkToken(input: $input) {
    linkToken
    expiration
    requestId
    mode
  }
}

{
  "input": {}
}

对于原生 Link，请将 deviceOs 传为 IOS 或 ANDROID，以便 identity-service 包含正确的 Plaid OAuth 重定向选项。

{
  "input": {
    "deviceOs": "IOS"
  }
}

2. 打开 Plaid Link

使用返回的 linkToken 初始化 Plaid Link。（参见下方 Web SDK 示例。）

3. 完成关联

在 Plaid Link 的 onSuccess 中，将返回的 public_token 发送给 TGS。

mutation CompletePlaidLink($input: CompletePlaidLinkInput!) {
  completePlaidLink(input: $input) {
    requiresAddress
    bankAccountId
    bankInstitutionAuthId
    newlyLinkedBankInstitutionAuthId
    bankInstitutionName
    platformItemId
    bankAccounts {
      bankInstitutionAuthId
      bankAccountId
      bankName
      lastFour
      type
      subtype
    }
  }
}

{
  "input": {
    "publicToken": "public-sandbox-..."
  }
}

4. 存储 `platformItemId`

保存完成响应中的 platformItemId。这是后续用于重新关联断开连接时的安全公共标识符。如果未返回，请为该用户调用 getPlaidBankAccounts 并从该响应中存储已持久化的 platformItemId。如果 completePlaidLink 返回 requiresAddress: true，在账户可用之前需要先附加地址——参见下文的附加地址。

Plaid Web SDK 示例

Plaid 的 Web SDK 脚本必须直接从 Plaid 的 CDN 加载。

<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>

通过 TGS 创建一个 Link 令牌，使用该令牌初始化 Plaid Link，并在 onSuccess 中将 Plaid 返回的 public_token 传回 TGS。不带参数调用 startPlaidLink() 会开始一次新的关联；调用 startPlaidLink(existingPlatformItemId) 会开始一次重新关联（参见 Relinking Disconnected Bank Accounts）。

const FLUZ_GRAPHQL_URL = '<fluz-api-base-url>/api/v1/graphql';
const fluzUserAccessToken = '<fluz-user-access-token>';

const fluzGraphql = async (query, variables) => {
  const response = await fetch(FLUZ_GRAPHQL_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${fluzUserAccessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query, variables }),
  });

  const body = await response.json();
  if (!response.ok || body.errors?.length) {
    throw new Error(body.errors?.[0]?.message ?? 'Fluz GraphQL request failed');
  }

  return body.data;
};

const createPlaidLinkToken = async (platformItemId) => {
  const data = await fluzGraphql(
    `
      mutation CreatePlaidLinkToken($input: CreatePlaidLinkTokenInput!) {
        createPlaidLinkToken(input: $input) {
          linkToken
          mode
        }
      }
    `,
    { input: { platformItemId } },
  );

  return data.createPlaidLinkToken;
};

const completePlaidLink = async (publicToken, platformItemId) => {
  const data = await fluzGraphql(
    `
      mutation CompletePlaidLink($input: CompletePlaidLinkInput!) {
        completePlaidLink(input: $input) {
          requiresAddress
          bankInstitutionAuthId
          newlyLinkedBankInstitutionAuthId
          bankAccountId
          platformItemId
          bankAccounts {
            bankInstitutionAuthId
            bankAccountId
            bankName
            lastFour
            type
            subtype
          }
        }
      }
    `,
    { input: { publicToken, platformItemId } },
  );

  return data.completePlaidLink;
};

const getPlaidBankAccounts = async (input) => {
  const data = await fluzGraphql(
    `
      query GetPlaidBankAccounts($input: PlaidBankAccountFilterInput) {
        getPlaidBankAccounts(input: $input) {
          platformItemId
          bankInstitutionAuthId
          bankAccountId
          bankInstitutionName
          lastFour
          type
          subtype
        }
      }
    `,
    { input },
  );

  return data.getPlaidBankAccounts;
};

const resolvePlatformItemId = async (completion) => {
  if (completion.platformItemId) return completion.platformItemId;

  const bankInstitutionAuthId =
    completion.bankInstitutionAuthId ?? completion.newlyLinkedBankInstitutionAuthId;
  const accounts = await getPlaidBankAccounts({ bankInstitutionAuthId });
  return accounts[0]?.platformItemId;
};

const startPlaidLink = async (platformItemId) => {
  const { linkToken } = await createPlaidLinkToken(platformItemId);

  const handler = window.Plaid.create({
    token: linkToken,
    onSuccess: async (publicToken, metadata) => {
      const result = await completePlaidLink(publicToken, platformItemId);
      const persistedPlatformItemId = await resolvePlatformItemId(result);

      await saveConnectionForRelinkLater({
        platformItemId: persistedPlatformItemId,
        bankInstitutionAuthId:
          result.bankInstitutionAuthId ?? result.newlyLinkedBankInstitutionAuthId,
        bankAccounts: result.bankAccounts,
        plaidLinkSessionId: metadata.link_session_id,
      });
    },
    onExit: (error, metadata) => {
      console.log('Plaid Link exited', { error, metadata });
    },
  });

  handler.open();
};

列出已关联账户

返回已认证用户的安全 Plaid 银行账户列表。

query GetPlaidBankAccounts($input: PlaidBankAccountFilterInput) {
  getPlaidBankAccounts(input: $input) {
    platformItemId
    bankInstitutionAuthId
    bankInstitutionName
    bankAccountId
    accountName
    lastFour
    type
    subtype
    status
  }
}

{
  "input": {
    "platformItemId": "plaid-item-id"
  }
}

附加地址

如果 completePlaidLink 返回了 requiresAddress: true，请为已关联的银行机构附加一个地址。

mutation CreatePlaidLinkAddress($input: CreatePlaidLinkAddressInput!) {
  createPlaidLinkAddress(input: $input) {
    addressId
  }
}

{
  "input": {
    "bankInstitutionAuthId": "bank-institution-auth-id",
    "address": {
      "streetAddressLine1": "123 Main St",
      "streetAddressLine2": "Apt 4",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  }
}

移除银行连接

从用户账户中移除一个 Plaid 银行机构。

mutation RemovePlaidBankInstitution($input: RemovePlaidBankInstitutionInput!) {
  removePlaidBankInstitution(input: $input) {
    removed
    bankInstitutionAuthId
  }
}

{
  "input": {
    "bankInstitutionAuthId": "bank-institution-auth-id",
    "reason": "USER_REQUESTED"
  }
}

安全边界

TGS 永远不会返回 Plaid 访问令牌、Plaid 公用令牌、身份匹配详情、银行账号或路由号。银行账户名称和昵称可能是用户输入的银行标签，仅作为账户元数据返回。 Identity-service 仍负责：

Plaid 令牌交换
Plaid 访问令牌存储
银行机构与银行账户的创建或修复
余额获取
历史交易摄取
银行机构移除
Plaid webhooks

TGS 不会直接暴露 identity-service，也不会新增公共的 Plaid webhook 路由。

不支持的流程

手动 Plaid 小额存款验证关联在此公共封装中被有意不支持。新的关联与重新关联必须使用常规的 Plaid Link 流程，该流程支持余额与历史交易。如果用户为同一机构发起新的关联而非选择重新关联，请将其当作正常的新关联来完成。Identity-service 负责银行账户去重与修复；在完成后存储返回的 platformItemId。

错误处理

如果 completePlaidLink 在 Plaid 已返回 public_token 后超时或失败，请在重试前，先使用已存储或预期的 platformItemId 调用 getPlaidBankAccounts。仅当 Plaid 从新的 Link 会话返回了新的 public_token 时再进行重试——Plaid 公用令牌有效期短且仅可使用一次。

​认证

​关联流程速览

​1. 创建 Link 令牌

​2. 打开 Plaid Link

​3. 完成关联

​4. 存储 platformItemId

​Plaid Web SDK 示例

​列出已关联账户

​附加地址

​移除银行连接

​安全边界

​不支持的流程

​错误处理

认证