透過 Plaid 連結銀行帳戶

使用以下作業讓使用者透過 Plaid Link 將銀行帳戶連結至 Fluz。連結是所有銀行帳戶資金加值的進入點：一旦帳戶連結後，您可以讀取其餘額與可用消費力、拉取其交易歷史、以及在連線日後中斷時進行修復——每項功能皆有各自的頁面說明。 Transactional Graph Service (TGS) 針對 Fluz 的 Plaid 整合提供公開的 GraphQL 封裝。Identity-service 仍是 Plaid 權杖、銀行帳戶匯入、餘額、歷史交易與 Plaid webhook 的權威系統。TGS 絕不會將 Plaid access tokens 或 public tokens 回傳給您的應用。

Auth

以包含 MANAGE_PAYMENT 權限範圍的 Fluz 使用者 Bearer 存取權杖 呼叫 /api/v1/graphql。 Plaid 欄位不允許使用 Basic auth。請先透過標準的 TGS 認證流程取得使用者存取權杖，接著以如下方式呼叫這些欄位：

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

鳥瞰連結流程

建立 Link token（createPlaidLinkToken）。
使用該 token 開啟 Plaid Link。
在 Plaid 的 onSuccess 中，將回傳的 public_token 傳回 TGS（completePlaidLink）。
儲存完成回應中的 platformItemId——這是之後用於重新連結的安全公開識別碼。

1. 建立 Link token

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 script 必須直接自 Plaid 的 CDN 載入。

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

透過 TGS 建立 Link token，以該 token 初始化 Plaid Link，並在 onSuccess 中將 Plaid 的 public_token 傳回 TGS。以不帶參數呼叫 startPlaidLink() 會開始新的連結；以 startPlaidLink(existingPlatformItemId) 會開始重新連結（見「重新連結中斷的銀行帳戶」）。

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 access tokens、Plaid public tokens、身分比對細節、銀行帳號或匯款路由號碼。銀行帳戶名稱與暱稱可能是使用者輸入的銀行標籤，僅作為帳戶中繼資料回傳。 Identity-service 仍負責：

Plaid 權杖交換
Plaid access token 儲存
銀行機構與銀行帳戶的建立或修復
餘額擷取
歷史交易匯入
銀行機構移除
Plaid webhooks

TGS 不會直接暴露 identity-service，亦不會新增公開的 Plaid webhook 路由。

不支援的流程

手動 Plaid 微額存款連結在此公開封裝中刻意不支援。新的連結與重新連結必須使用一般的 Plaid Link 流程，該流程支援餘額與歷史交易。若使用者為同一機構啟動了新連結而非選擇重新連結，請將其完成為一般的新連結。Identity-service 負責銀行帳戶去重與修復；在完成後儲存回傳的 platformItemId。

錯誤處理

若 completePlaidLink 在 Plaid 已回傳 public_token 後逾時或失敗，請在重試前，先以已儲存或預期的 platformItemId 呼叫 getPlaidBankAccounts。僅在 Plaid 於新的 Link 工作階段回傳新的 public_token 時才重試——Plaid public tokens 具短效且一次性使用的特性。

​Auth

​鳥瞰連結流程

​1. 建立 Link token

​2. 開啟 Plaid Link

​3. 完成連結

​4. 儲存 platformItemId

​Plaid Web SDK 範例

​列出已連結帳戶

​附加地址

​移除銀行連線

​安全邊界

​不支援的流程

​錯誤處理