转账到另一个 Fluz 账户

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

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

快速开始

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

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

Authorization: Bearer <user-oauth-token>

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

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

Authorization: Basic <Api-Key>

认证

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

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

Bearer Token

使用通过 generateUserAccessToken 获取的用户 OAuth 令牌，或通过 OAuth 刷新流程获取。令牌必须包含 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 时不支持资金来源。”

📘 参见添加费用明细以获取有关上传附件以及使用备注与类别的完整说明。

TransferDirection

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

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

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

响应

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

示例

向用户收款（Bearer）

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

Authorization: Bearer <user-oauth-token>

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

向用户发放资金（Basic Auth）

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

Authorization: Basic <API-Key>

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

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

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

Authorization: Bearer <user-oauth-token>

成功响应

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

幂等性

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

错误

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

{
  "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 转账。
余额不足	发送方现金余额小于转账金额。

​快速开始

​认证

​Bearer Token

​Basic Auth

​输入

​CreateTransferInput

​TransferDirection

​响应

​示例

​向用户收款（Bearer）

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

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

​成功响应

​幂等性

​错误

​常见错误