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

# 转账到另一个 Fluz 账户

在你的应用余额与用户余额之间，或在两个用户之间移动资金。

> “要求：你的应用必须是公共应用。”

## 快速开始

从用户向你的应用发送 \$10：

```graphql theme={null}
mutation {
  createTransfer(input: {
    idempotencyKey: "550e8400-e29b-41d4-a716-446655440000"
    amount: 10
  }) {
    success
    message
    transferId
  }
}
```

```text theme={null}
Authorization: Bearer <user-oauth-token>
```

从你的应用向某位用户发送 \$10：

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

```text theme={null}
Authorization: Basic <Api-Key>
```

***

## 认证

转账支持两种认证方式。你选择的方法决定谁是发送方。

| 方法           | 发送方  | 使用场景                    |
| :----------- | :--- | :---------------------- |
| Bearer token | 用户   | 向用户收款（用户 → 你）或在用户之间转移资金 |
| Basic Auth   | 你的应用 | 向用户发放资金（你 → 用户）         |

### Bearer Token

使用通过 `generateUserAccessToken` 获取的用户 OAuth 令牌，或通过 [OAuth 刷新流程](/refresh-o-auth-access-token) 获取。令牌必须包含 `MAKE_PAYOUT_TRANSFER_SEND` 范围。

### Basic Auth

使用你的应用的 Api Key。

***

## 输入

### CreateTransferInput

| 字段                  | 类型                  | 必填    | 说明                                                   |
| :------------------ | :------------------ | :---- | :--------------------------------------------------- |
| idempotencyKey      | String!             | 是     | 你生成的唯一 UUID，用于防止重复转账。使用相同 key 重试将返回原始结果。             |
| amount              | Float!              | 是     | 转账金额。必须为正数。                                          |
| destination         | TransferDestination | 视情况而定 | 资金接收方。**Basic Auth 必填**。对于 Bearer token，如省略则默认为你的应用。 |
| bankCardId          | UUID                | 否     | 使用用户绑定的银行卡为本次转账提供资金，而非其现金余额。仅限 Bearer token。         |
| bankAccountId       | UUID                | 否     | 通过 ACH 使用用户的银行账户为本次转账提供资金。仅限 Bearer token。           |
| paypalVaultId       | UUID                | 否     | 使用用户绑定的 PayPal 为本次转账提供资金。仅限 Bearer token。            |
| memo                | String              | 否     | 附加到此交易的自由文本备注。最多 255 个字符。                            |
| transactionCategory | String              | 否     | 附加到此交易的类别标签。自由格式——首次使用将自动创建类别。                       |
| attachmentId        | UUID                | 否     | 先前上传文件（PDF 或 PNG）的 ID，用于附加到此交易。请先使用交易备注附件端点上传文件。     |

> “每个请求只能指定一个资金来源。若未提供，将从发送方的现金余额中扣款。
>
> 使用 Basic Auth 时不支持资金来源。”

📘 参见 [添加费用明细](/features/add-expense-details) 以获取有关上传附件以及使用备注与类别的完整说明。

### TransferDirection

通过账户 ID 或你在创建用户时分配的外部参考 ID 标识收款人。二者择一，不可同时提供。

| 字段                  | 类型     | 必填    | 说明                                  |
| :------------------ | :----- | :---- | :---------------------------------- |
| accountId           | UUID   | 是     | 收款人的 Fluz 账户 ID。                    |
| externalReferenceId | String | 是     | 你在系统中为该用户分配的外部参考 ID。                |
| userCashBalanceId   | UUID   | 视情况而定 | 可选。定位收款账户上的特定现金余额。如省略，系统将自动选择正确的余额。 |

> “收款人必须是你的应用的注册用户。”

***

## 响应

| 字段         | 类型       | 说明                                 |
| :--------- | :------- | :--------------------------------- |
| success    | Boolean! | 转账是否完成。                            |
| message    | String!  | 人类可读的结果描述。                         |
| transferId | UUID     | 转账的唯一 ID。当 `success` 为 `true` 时存在。 |

***

## 示例

### 向用户收款（Bearer）

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

```text theme={null}
Authorization: Bearer <user-oauth-token>
```

无需指定 destination——默认为你的应用。可选地包含 `bankCardId`、`bankAccountId` 或 `paypalVaultId`，以从外部来源而非用户现金余额中出资。

### 向用户发放资金（Basic Auth）

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

```text theme={null}
Authorization: Basic <API-Key>
```

使用 `externalReferenceId` 替代 `accountId`，以你分配的 ID 标识收款人。

### 在两个用户之间转账（Bearer）

```graphql theme={null}
mutation {
  createTransfer(input: {
    idempotencyKey: "550e8400-e29b-41d4-a716-446655440002"
    amount: 25.00
    destination: {
      accountId: "b2c3d4e5-f6a7-8901-bcde-f23456789012"
    }
  }) {
    success
    message
    transferId
  }
}
```

```text theme={null}
Authorization: Bearer <user-oauth-token>
```

### 成功响应

```json theme={null}
{
  "data": {
    "createTransfer": {
      "success": true,
      "message": "Transfer created successfully.",
      "transferId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    }
  }
}
```

***

## 幂等性

每个请求必须包含唯一的 `idempotencyKey`（由你生成的字符串）。如果同一个 key 被多次发送，API 将返回原始请求的结果，而不会创建重复转账。key 的有效期为 10 分钟。

***

## 错误

错误遵循标准 GraphQL 错误格式：

```json theme={null}
{
  "errors": [
    {
      "message": "Amount must be positive.",
      "extensions": {
        "code": "ARG-0001",
        "name": "InvalidArguments",
        "status_code": 422
      }
    }
  ]
}
```

### 常见错误

| 错误                                      | 原因                                                                   |
| :-------------------------------------- | :------------------------------------------------------------------- |
| 缺少 idempotencyKey 或 amount              | 未提供必填字段。                                                             |
| Amount must be positive                 | 金额为零或负数。                                                             |
| 使用 Basic auth 时必须提供 Destination         | 使用 Basic Auth 的请求必须指定 destination。                                   |
| 使用 Basic auth 时不支持资金来源                  | 从 Basic Auth 请求中移除 `bankCardId` / `bankAccountId` / `paypalVaultId`。 |
| 一次仅允许一个资金来源                             | 提供了多个资金来源。仅传递一个。                                                     |
| 只能提供 accountId 或 externalReferenceId 之一 | destination 同时包含了两个标识符。请选择其一。                                        |
| 目标账户未授权此应用                              | 收款人不是你的应用的注册用户。                                                      |
| 未找到具有此外部参考 ID 的用户                       | `externalReferenceId` 与你的应用中的任何用户都不匹配。                               |
| 用户未配置现金余额                               | 发送方或收款人在所需的赞助银行处没有现金余额。                                              |
| 个人应用不支持 Basic auth                      | 将你的应用升级到 `ACTIVE` 状态以使用 Basic Auth 转账。                               |
| 余额不足                                    | 发送方现金余额小于转账金额。                                                       |