> ## 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 流程进行修复，随后余额和消费能力才会再次刷新。

## 认证

使用包含 `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 访问令牌，然后请求 identity-service 创建一个 Plaid 的更新模式（update-mode）Link 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` 助手可同时处理两种情况。调用 `startPlaidLink(existingPlatformItemId)` 可修复断开的连接；调用 `startPlaidLink()`（不传参数）用于全新的链接。

## 错误处理

如果 `createPlaidLinkToken` 失败并提示 `No active Plaid connection found for the provided platformItemId.`，则将已存储的连接视为无法重新链接，并引导用户进行新的银行链接。

如果用户为同一机构开始了新的链接而不是选择重新链接，请将其按正常的新链接完成——identity-service 负责银行账户去重和修复。完成后存储返回的 `platformItemId`。

<br />