提領至外部帳戶

概覽

提領功能允許使用者將資金從其 Fluz 餘額轉出至外部帳戶。使用者可自以下兩種類型的餘額進行提領：

現金餘額（Cash Balance） - 使用者存入其 Fluz 帳戶的資金
獎勵餘額（Rewards Balance） - 由購物累積的現金回饋

Fluz 支援以下提領方式：

方法	說明
`BANK_ACH`	轉帳至已連結的銀行帳戶（ACH）
`BANK_CARD`	推送至卡片（push-to-card），轉至已連結的金融簽帳卡
`PAYPAL`	轉至已連結的 PayPal 帳戶
`VENMO`	轉至已連結的 Venmo 帳戶

提領現金餘額

範例請求

你可以使用 withdrawCashBalance mutation 發起提領。此 mutation 會將資金從使用者的 Fluz 餘額轉至其指定的外部帳戶。

{
  "query": "mutation withdrawCashBalance($input: WithdrawCashBalanceInput!) { withdrawCashBalance(input: $input) { withdraws { withdrawId amount processingFee chargedFee status displayStatus withdrawMethod withdrawSource submissionDate createdAt updatedAt transactionLogId bankAccountId userCashBalanceId seatId } balances { cashBalance { availableBalance totalBalance } rewardsBalance { availableBalance totalBalance } } } }",
  "variables": {
    "input": {
      "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
      "amount": 100.00,
      "method": "BANK_ACH",
      "source": "CASH_BALANCE",
      "bankAccountId": "a578fe07-7165-47b8-b147-2251c99b7fc1",
      "cashBalanceId": "8d197a56-53df-439b-85cd-bb88dfca9a5f"
    }
  }
}

此 mutation 需要 WithdrawCashBalanceInput 輸入型別。任何在 schema 中以驚嘆號（!）標記的欄位皆為必填，必須包含於請求中。

輸入欄位

欄位名稱	型別	說明
`idempotencyKey`	`UUID!`	用戶端產生的唯一 UUID，確保請求只被處理一次。可避免同一請求重送時造成重複提領。
`amount`	`Float!`	提領金額。必須大於 0。
`method`	`WithdrawMethods!`	要使用的提領方式。可為：`PAYPAL`、`BANK_ACH`、`BANK_CARD`、`VENMO`。
`source`	`WithdrawSource`	要提領資金的來源餘額。可為：`CASH_BALANCE`、`REWARDS_BALANCE`。若未指定，預設為 `CASH_BALANCE`。
`bankAccountId`	`UUID`	當 `method` 為 `BANK_ACH` 時必填。ACH 提領所使用之已連結銀行帳戶識別碼。
`bankCardId`	`UUID`	當 `method` 為 `BANK_CARD` 時必填。推送至卡片提領所使用之已連結金融簽帳卡識別碼。
`paypalVaultId`	`UUID`	當 `method` 為 `PAYPAL` 時必填。已連結 PayPal 帳戶之識別碼。
`venmoAccountId`	`UUID`	當 `method` 為 `VENMO` 時必填。已連結 Venmo 帳戶之識別碼。
`cashBalanceId`	`UUID`	欲提領之特定現金餘額帳戶識別碼。當 `source` 為 `CASH_BALANCE` 時必填。

WithdrawCashBalanceInput

{
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 100.00,
  "method": "BANK_ACH",
  "source": "CASH_BALANCE",
  "bankAccountId": "a578fe07-7165-47b8-b147-2251c99b7fc1",
  "bankCardId": null,
  "paypalVaultId": null,
  "venmoAccountId": null,
  "cashBalanceId": "8d197a56-53df-439b-85cd-bb88dfca9a5f"
}

範例回應

withdrawCashBalance mutation 的回應包含提領記錄與使用者更新後的餘額。

{
  "data": {
    "withdrawCashBalance": {
      "withdraws": [
        {
          "withdrawId": "c4d5e6f7-8901-2345-6789-0abcdef12345",
          "amount": "100.00",
          "processingFee": "0.00",
          "chargedFee": "0.00",
          "status": "PENDING",
          "displayStatus": "PROCESSING",
          "withdrawMethod": "BANK_ACH",
          "withdrawSource": "CASH_BALANCE",
          "submissionDate": "2024-01-15T10:30:00Z",
          "createdAt": "2024-01-15T10:30:00Z",
          "updatedAt": "2024-01-15T10:30:00Z",
          "transactionLogId": "f1234567-89ab-cdef-0123-456789abcdef",
          "bankAccountId": "a578fe07-7165-47b8-b147-2251c99b7fc1",
          "userCashBalanceId": "8d197a56-53df-439b-85cd-bb88dfca9a5f",
          "seatId": "e7979eb7-1727-48ed-8c5a-c56532908c1e"
        }
      ]
    }
  }
}

回應欄位

Withdraw 物件

欄位名稱	型別	說明
`withdrawId`	`UUID!`	提領的唯一識別碼。
`amount`	`String!`	提領金額。
`processingFee`	`String!`	提領處理費。
`chargedFee`	`String!`	向使用者收取的提領費用。
`status`	`String!`	提領的內部狀態（例如：`PENDING`、`COMPLETED`、`FAILED`）。
`displayStatus`	`String!`	使用者可見的顯示狀態（例如：`PROCESSING`、`COMPLETE`）。
`withdrawMethod`	`WithdrawMethods!`	所使用的提領方式。
`withdrawSource`	`WithdrawSource!`	提領資金的來源餘額。
`submissionDate`	`DateTime!`	提領提交的日期與時間。
`createdAt`	`DateTime!`	提領建立的日期與時間。
`updatedAt`	`DateTime!`	提領最後更新的日期與時間。
`transactionLogId`	`UUID`	關聯交易日誌的識別碼。
`externalTransactionId`	`String`	來自金流閘道的外部交易識別碼（適用於 ACH）。
`payoutId`	`String`	來自金流閘道的撥款識別碼（適用於 PayPal/Venmo）。
`emailAddress`	`String`	與此提領關聯的電子郵件地址。
`bankAccountId`	`UUID`	使用之銀行帳戶的識別碼（若適用）。
`userCashBalanceId`	`UUID`	進行提領之使用者現金餘額帳戶識別碼。
`seatId`	`UUID`	與帳戶關聯的 seat ID。

必要 Scope

此 mutation 需要在存取權杖上授與 MANAGE_PAYMENT scope。

generateUserAccessToken(
  userId: "...",
  accountId: "...",
  scopes: [MANAGE_PAYMENT]
)

各帳戶型態對應的提領方式

方法	必填欄位	備註
`BANK_ACH`	`bankAccountId`	標準 ACH 轉帳。通常於 1-3 個工作天內入帳。無手續費。
`BANK_CARD`	`bankCardId`	推送至卡片的即時轉帳。僅適用於符合條件的金融簽帳卡。可能產生手續費。
`PAYPAL`	`paypalVaultId`	轉至已連結的 PayPal 帳戶。可能產生手續費。
`VENMO`	`venmoAccountId`	轉至已連結的 Venmo 帳戶。可能產生手續費。

錯誤處理

常見錯誤情境：

錯誤代碼	說明
`MISSING_ARGUMENT`	缺少必要欄位（例如：`idempotencyKey`、`amount`、`method`）。
`INVALID_AMOUNT`	金額為零或負數。
`INSUFFICIENT_FUNDS`	使用者餘額不足，無法完成提領。
`WITHDRAW_ERROR`	一般提領錯誤。請檢查錯誤訊息以取得詳細資訊。

錯誤回應範例

{
  "errors": [
    {
      "message": "Missing required argument - require idempotencyKey.",
      "extensions": {
        "code": "MISSING_ARGUMENT"
      }
    }
  ]
}

多筆提領

在某些情況下，單一提領請求可能會產生多筆提領記錄。當提領金額分攤至多個 seats（網路節點/位置）時，會出現此情形。回應中將包含所有建立的提領記錄。

{
  "data": {
    "withdrawCashBalance": {
      "withdraws": [
        {
          "withdrawId": "withdraw-1",
          "amount": "75.00",
          "seatId": "seat-1"
        },
        {
          "withdrawId": "withdraw-2", 
          "amount": "25.00",
          "seatId": "seat-2"
        }
      ]
    }
  }
}

最佳實務

一律使用唯一的冪等鍵（idempotency key） - 為每次提領請求產生新的 UUID，以避免重複交易。
提領前先檢查餘額 - 使用 getWallet 查詢，確認使用者有足夠資金再發起提領。
處理待處理狀態 - 提領可能需要時間處理。可透過 status 欄位追蹤當前狀態。
保存交易參考資料 - 儲存 withdrawId 與 transactionLogId 以利對帳與客服支援。

變更記錄

v1.2.0 - 2024-11-20

Schema 調整與欄位清理

自 WithdrawCashBalanceInput 移除 isExpedited 欄位 — 加速 ACH 已無法透過 API 設定
將 Withdraw 型別中的 seat_id 欄位由選填改為必填（UUID → UUID!）
更新 BANK_CARD 方法的說明，移除「加速」相關敘述

v1.1.0 - 2024-10-15

新增 Venmo 支援與獎勵餘額提領

於 WithdrawMethods 列舉新增 VENMO
於 WithdrawCashBalanceInput 新增 venmoAccountId 欄位
於 WithdrawSource 列舉新增 REWARDS_BALANCE，支援提領現金回饋
於 Withdraw 回應型別新增 seat_id 欄位，以支援多 seat 帳戶追蹤

v1.0.0 - 2024-09-01

初始發佈

推出 withdrawCashBalance mutation，需具備 MAKE_WITHDRAWAL scope
新增 WithdrawMethods 列舉，包含 PAYPAL、BANK_ACH、BANK_CARD
新增 WithdrawSource 列舉，包含 CASH_BALANCE
新增具冪等支援的 WithdrawCashBalanceInput 輸入型別
新增 Withdraw 回應型別，提供完整提領記錄詳情
新增 WithdrawCashBalanceResponse 型別，回傳提領記錄與更新後的餘額
整合 payout-service 以處理提領流程
新增應用程式動作日誌以供稽核追蹤

​概覽

​提領現金餘額

​範例請求

​輸入欄位

​WithdrawCashBalanceInput

​範例回應

​回應欄位

​Withdraw 物件

​必要 Scope

​各帳戶型態對應的提領方式

​錯誤處理

​錯誤回應範例

​多筆提領

​最佳實務

​變更記錄

​v1.2.0 - 2024-11-20

​v1.1.0 - 2024-10-15

​v1.0.0 - 2024-09-01

概覽