> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 重新連結銀行帳戶

先前已連結的 Plaid 連線可能會中斷——例如使用者變更了其銀行憑證。中斷期間，Fluz 無法擷取更新後的餘額，因此必須透過 Plaid 的 **update-mode** Link 流程進行修復，之後餘額與消費力才會再次更新。

## Auth

使用包含 `MANAGE_PAYMENT` 的 Fluz 使用者 Bearer 存取權杖呼叫 `/api/v1/graphql`。這些欄位不允許使用 Basic auth。

```http theme={null}
Authorization: Bearer <fluz-user-access-token>
```

## 偵測何時需要重新連結

有兩個可靠的訊號：

1. `refreshPlaidBankConnections `**回傳** `verifyMembers`**。** 每個項目都指出需要修復的連線；使用其 `platformItemId` 來啟動下方的重新連結流程。（參見「*管理銀行帳戶消費力*」中的該 mutation。）
2. `createPlaidLinkToken `**失敗**，訊息為 `No active Plaid connection found for the provided platformItemId.` —— 表示已儲存的連線不再可重新連結；請引導使用者改為進行**新的**銀行連結（參見「*連結 Plaid 銀行帳戶*」）。

## 重新連結流程

你需要已中斷連線所儲存的 `platformItemId`。

### 1. 使用已儲存的 `platformItemId` 建立 Link token

```graphql theme={null}
mutation CreatePlaidLinkToken($input: CreatePlaidLinkTokenInput!) {
  createPlaidLinkToken(input: $input) {
    linkToken
    expiration
    requestId
    mode
  }
}
```

```json theme={null}
{
  "input": {
    "platformItemId": "plaid-item-id"
  }
}
```

TGS 會使用 `platformItemId` 從 identity-service 取回 Plaid access token，接著請求 identity-service 建立 Plaid 的更新模式（update-mode）Link token。access token 絕不會回傳給呼叫端。

對於**原生**重新連結，同時傳入 `deviceOs` 為 `IOS` 或 `ANDROID`。

### 2. 開啟 Plaid Link

使用回傳的 `linkToken` 初始化 Plaid Link。

### 3. 完成重新連結

在 Plaid Link 的 `onSuccess` 中，使用 `publicToken` 與相同的 `platformItemId` **兩者皆提供** 來完成流程。

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

```json theme={null}
{
  "input": {
    "publicToken": "public-sandbox-...",
    "platformItemId": "plaid-item-id"
  }
}
```

### 4. 更新已儲存的 `platformItemId`

如果回應中的 `platformItemId` 有變更，請更新你儲存的值。若未回傳，請呼叫使用者的 `getPlaidBankAccounts`，並從該回應中儲存持久化的 `platformItemId`。

## 使用 Web SDK 進行重新連結

在「*連結 Plaid 銀行帳戶*」中的共用 `startPlaidLink` helper 可同時處理兩種情況。呼叫 `startPlaidLink(existingPlatformItemId)` 可修復中斷的連線；若是全新連結，則呼叫不帶參數的 `startPlaidLink()`。

## 錯誤處理

若 `createPlaidLinkToken` 因 `No active Plaid connection found for the provided platformItemId.` 失敗，將已儲存的連線視為無法再重新連結，並引導使用者改為進行新的銀行連結。

若使用者針對相同機構啟動新的連結而不是選擇重新連結，請將其當作一般新連結完成——identity-service 負責銀行帳戶的去重與修復。在完成後儲存回傳的 `platformItemId`。

<br />