提領至外部帳戶

Overview

提領可讓使用者將資金從其 Fluz 餘額轉移到外部帳戶。使用者可以從兩種類型的餘額提領：

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

Fluz 支援以下提領方式：

Method	Description
`BANK_ACH`	ACH 轉帳至已連結的銀行帳戶
`BANK_CARD`	推播至卡的轉帳至已連結的金融卡
`PAYPAL`	轉帳至已連結的 PayPal 帳戶
`VENMO`	轉帳至已連結的 Venmo 帳戶

Withdraw Cash Balance

Sample Request

你可以使用 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 輸入型別。結構中以驚嘆號（!）標記的欄位為必填，必須包含於請求中。

Input Fields

Field Name	Type	Description
`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"
}

Sample Response

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"
        }
      ]
    }
  }
}

Response Fields

Withdraw Object

Field Name	Type	Description
`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。

Required Scope

此 mutation 需要將 MAKE_WITHDRAWAL 權限範圍授與存取權杖。

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

Withdrawal Methods by Account Type

Method	Required Field	Notes
`BANK_ACH`	`bankAccountId`	標準 ACH 轉帳。通常於 1-3 個工作天內到帳。無手續費。
`BANK_CARD`	`bankCardId`	推播至卡的即時轉帳。僅適用於符合條件的金融卡。可能收取手續費。
`PAYPAL`	`paypalVaultId`	轉帳至已連結的 PayPal 帳戶。可能收取手續費。
`VENMO`	`venmoAccountId`	轉帳至已連結的 Venmo 帳戶。可能收取手續費。

Error Handling

常見錯誤情境：

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

Example Error Response

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

Multiple Withdrawals

在某些情況下，單一提領請求可能會產生多筆提領紀錄。當提領金額分散到多個 seats（網路位置）時，會出現此情況。回應會包含所有建立的提領紀錄。

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

Best Practices

一律使用唯一的冪等鍵（idempotency keys） - 為每次提領請求產生新的 UUID，以防止重複交易。
提領前先檢查餘額 - 使用 getWallet 查詢在發起提領前確認使用者有足夠資金。
處理待處理狀態 - 提領可能需要時間處理。status 欄位會指出目前的處理狀態。
儲存交易參考 - 保留 withdrawId 與 transactionLogId 以便對帳與客服支援。

Changelog

v1.2.0 - 2024-11-20

結構優化與欄位清理

從 WithdrawCashBalanceInput 移除 isExpedited 欄位 —— 已不再可透過 API 設定加速 ACH
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 權限範圍
新增含 PAYPAL、BANK_ACH、BANK_CARD 方法的 WithdrawMethods 列舉
新增 WithdrawSource 列舉並包含 CASH_BALANCE 來源
新增支援冪等的 WithdrawCashBalanceInput 輸入型別
新增具完整提領紀錄細節的 Withdraw 回應型別
新增回傳提領紀錄與更新餘額的 WithdrawCashBalanceResponse 型別
整合 payout-service 以處理提領
新增應用程式動作記錄以供稽核追蹤

​Overview

​Withdraw Cash Balance

​Sample Request

​Input Fields

​WithdrawCashBalanceInput

​Sample Response

​Response Fields

​Withdraw Object

​Required Scope

​Withdrawal Methods by Account Type

​Error Handling

​Example Error Response

​Multiple Withdrawals

​Best Practices

​Changelog

​v1.2.0 - 2024-11-20

​v1.1.0 - 2024-10-15

​v1.0.0 - 2024-09-01