轉帳到另一個 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>

驗證方式

Transfer 支援兩種驗證方式。你選擇的方法會決定「寄款方」是誰。

方法	寄款方	使用情境
Bearer token	使用者	向使用者收款（使用者 → 你）或在使用者之間移轉資金
Basic Auth	你的應用程式	向使用者撥款（你 → 使用者）

Bearer Token

使用透過 generateUserAccessToken 或 OAuth 重新整理流程取得的使用者 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 時不支援資金來源。」

📘 參見新增費用詳情以取得上傳附件與使用備註、分類的完整資訊。

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（你產生的字串）。如果同一個金鑰被多次傳送，API 會回傳原始請求的結果，而不會建立重複轉帳。金鑰有效期間為 10 分鐘。

錯誤

錯誤遵循標準的 GraphQL 錯誤格式：

{
  "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	寄款方的現金餘額低於轉帳金額。

​快速開始

​驗證方式

​Bearer Token

​Basic Auth

​輸入

​CreateTransferInput

​TransferDirection

​回應

​範例

​向使用者收款（Bearer）

​向使用者撥款（Basic Auth）

​兩位使用者之間的轉帳（Bearer）

​成功回應

​冪等性

​錯誤

​常見錯誤