> ## 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 ``` 從你的應用程式傳送 \$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 ``` *** ## 驗證方式 Transfer 支援兩種驗證方式。你選擇的方法會決定「寄款方」是誰。 | 方法 | 寄款方 | 使用情境 | | :----------- | :----- | :------------------------- | | Bearer token | 使用者 | 向使用者收款（使用者 → 你）或在使用者之間移轉資金 | | Basic Auth | 你的應用程式 | 向使用者撥款（你 → 使用者） | ### Bearer Token 使用透過 `generateUserAccessToken` 或 [OAuth 重新整理流程](/refresh-o-auth-access-token) 取得的使用者 OAuth 權杖。該權杖必須包含 `MAKE_PAYOUT_TRANSFER_SEND` 範圍。 ### Basic Auth 使用你的應用程式 Api Key。 *** ## 輸入 ### CreateTransferInput | 欄位 | 類型 | 必填 | 說明 | | :------------------ | :------------------ | :-- | :--------------------------------------------------------- | | idempotencyKey | String! | 是 | 你產生的唯一 UUID，以防止重複轉帳。以相同金鑰重送會回傳原始結果。 | | 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 ``` 不需要指定 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 ``` 使用 `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 ``` ### 成功回應 ```json theme={null} { "data": { "createTransfer": { "success": true, "message": "Transfer created successfully.", "transferId": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } ``` *** ## 冪等性 每個請求都必須包含唯一的 `idempotencyKey`（你產生的字串）。如果同一個金鑰被多次傳送，API 會回傳原始請求的結果，而不會建立重複轉帳。金鑰有效期間為 10 分鐘。 *** ## 錯誤 錯誤遵循標準的 GraphQL 錯誤格式： ```json theme={null} { "errors": [ { "message": "Amount must be positive.", "extensions": { "code": "ARG-0001", "name": "InvalidArguments", "status_code": 422 } } ] } ``` ### 常見錯誤 | 錯誤 | 成因 | | :-------------------------------------------------------- | :-------------------------------------------------------------------- | | Missing idempotencyKey or amount | 未提供必要欄位。 | | Amount must be positive | 金額為零或負數。 | | Destination is required when using Basic auth | 使用 Basic Auth 的請求必須指定 destination。 | | Funding sources are not supported when using Basic auth | 請從 Basic Auth 請求中移除 `bankCardId` / `bankAccountId` / `paypalVaultId`。 | | Only one funding source is allowed at a time | 提供了多個資金來源。僅可傳入一個。 | | Provide either accountId or externalReferenceId, not both | destination 同時包含兩種識別方式。請擇一使用。 | | Destination account has not authorized this application | 收款人不是你應用程式的註冊使用者。 | | No user found with this external reference ID | `externalReferenceId` 與你應用程式中的任何使用者都不相符。 | | User does not have a cash balance configured | 寄款方或收款方在所需的贊助銀行沒有設定現金餘額。 | | Basic auth is not supported for personal applications | 請將你的應用程式升級至 `ACTIVE` 狀態以使用 Basic Auth 轉帳。 | | Insufficient balance | 寄款方的現金餘額低於轉帳金額。 |