> ## 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.

# 請求帳戶轉帳核准

`requestAccountTransfer`

提交帳戶對帳戶轉帳的管理者核准請求。當獲得核准後，Fluz 會以與 `createTransfer` 相同的語意執行轉帳。

當使用者或應用程式在於 Fluz 帳戶間移動資金前需要管理者簽核時使用此功能。若是在同一個帳戶內的消費帳戶之間轉帳，請改用 `requestInternalTransfer`。

## 權限範圍

| 動作    | 範圍                         |
| ----- | -------------------------- |
| 建立請求  | `REQUEST_ACCOUNT_TRANSFER` |
| 列出請求  | `LIST_APPROVALS`           |
| 核准或拒絕 | `MANAGE_APPROVALS`         |

## Webhook 識別子

| 欄位             | 值        |
| -------------- | -------- |
| `approvalType` | `PAYOUT` |
| `approvalCode` | `500402` |

Webhook 事件：`APPROVAL_CREATE`、`APPROVAL_APPROVE`、`APPROVAL_DECLINE`，以及在執行失敗時的 `APPROVAL_HANDLER_ERROR`。

> 內部轉帳與帳戶轉帳共用相同的 `approvalType` 與 `approvalCode`。請使用原始請求的 mutation，或在您的整合中檢視核准的 payload 以區分它們。

## 建立請求

輸入與 [Transfer to Another Fluz Account](/features/transfer-to-another-fluz-wallet) 相同。寄件者由驗證決定；目的地與資金來源遵循 `createTransfer` 的相同規則。

### RequestAccountTransferInput

| 欄位                    | 類型                  | 必填    | 說明                                            |
| --------------------- | ------------------- | ----- | --------------------------------------------- |
| `idempotencyKey`      | UUID                | 是     | 用於在核准後防止重複轉帳的唯一金鑰                             |
| `amount`              | Float               | 是     | 轉帳金額。必須大於零                                    |
| `destination`         | TransferDestination | 視情況而定 | 收款帳戶。對於 Basic Auth 必填；對於 Bearer 選填（預設為您的應用程式） |
| `bankCardId`          | UUID                | 否     | 由已連結的銀行卡資金來源。僅限 Bearer 權杖                     |
| `bankAccountId`       | UUID                | 否     | 透過 ACH 入金。僅限 Bearer 權杖                        |
| `paypalVaultId`       | UUID                | 否     | 由 PayPal 資金來源。僅限 Bearer 權杖                    |
| `memo`                | String              | 否     | 交易備註                                          |
| `transactionCategory` | String              | 否     | 類別標籤；首次使用時會自動建立                               |
| `attachmentId`        | String              | 否     | 先前上傳之交易附件的 ID                                 |

### TransferDestination

| 欄位                    | 類型     | 說明               |
| --------------------- | ------ | ---------------- |
| `accountId`           | UUID   | 收款 Fluz 帳戶 ID    |
| `externalReferenceId` | String | 您系統中的收款方外部參考 ID  |
| `userCashBalanceId`   | UUID   | 收款帳戶上的目標消費帳戶（選填） |

請提供 `accountId` 或 `externalReferenceId` 其中之一，不可同時提供。

### 驗證注意事項

| 方法         | 寄件者    | 說明                         |
| ---------- | ------ | -------------------------- |
| Bearer 權杖  | 已驗證使用者 | 允許使用資金來源；目的地為選填（預設為您的應用程式） |
| Basic Auth | 您的應用程式 | 目的地必填；不允許使用資金來源            |

### 範例 Mutation — 使用者到應用程式

```graphql theme={null}
mutation {
  requestAccountTransfer(
    input: {
      idempotencyKey: "550e8400-e29b-41d4-a716-446655440000"
      amount: 100.00
    }
  ) {
    success
    messageId
    error {
      code
      message
    }
  }
}
```

### 範例 Mutation — 應用程式到使用者

```graphql theme={null}
mutation {
  requestAccountTransfer(
    input: {
      idempotencyKey: "550e8400-e29b-41d4-a716-446655440001"
      amount: 50.00
      destination: {
        accountId: "c3d4e5f6-a7b8-9012-cdef-345678901234"
      }
    }
  ) {
    success
    messageId
    error {
      code
      message
    }
  }
}
```

### 範例回應

```json theme={null}
{
  "data": {
    "requestAccountTransfer": {
      "success": true,
      "messageId": "1234567890"
    }
  }
}
```

`idempotencyKey` 會被保留，並在核准後執行轉帳時使用。

## 核准請求

以 `approvalId` 呼叫 `approveApprovalRequest`。需要 `MANAGE_APPROVALS`。

```graphql theme={null}
mutation {
  approveApprovalRequest(approvalId: "07df5653-43a8-4532-9881-3ab5857bbe12") {
    success
    approvalId
    action
  }
}
```

在核准後，Fluz 會執行帳戶轉帳。

## 拒絕請求

以 `approvalId` 呼叫 `declineApprovalRequest`。需要 `MANAGE_APPROVALS`。

```graphql theme={null}
mutation {
  declineApprovalRequest(approvalId: "07df5653-43a8-4532-9881-3ab5857bbe12") {
    success
    approvalId
    action
  }
}
```

當請求被拒絕時，不會執行任何轉帳。