提領至外部帳戶

Overview

提領允許使用者將資金從其 Fluz 餘額轉至外部帳戶。使用者可自兩種餘額提領：

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

Fluz 支援以下提領方式：

Method	Description
`BANK_ACH`	透過 ACH 匯款至已連結的銀行帳戶
`BANK_CARD`	透過推播至卡（push-to-card）匯款至已連結的金融卡，以原始入帳交易（OCT）方式入帳
`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 輸入型別。任何在 schema 中以驚嘆號（!）標記的欄位都是必填，且必須包含於請求中。

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` 時必填。
`isExpedited`	`Boolean`	若為 `true`，提領將即時處理。若為 `false` 或省略，則依標準結算時程處理。目前適用於 `BANK_CARD` 提領，兩種速度的費率不同 — 可用 `getWithdrawFeeEstimate` 預覽。

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",
  "isExpedited": false
}

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 scope 授與該存取權杖。getWithdrawFeeEstimate 查詢也需要相同的 scope。

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

Withdrawal Methods by Account Type

Method	Required Field	Notes
`BANK_ACH`	`bankAccountId`	標準 ACH 匯款。通常於 1-3 個工作天內結算。無手續費。
`BANK_CARD`	`bankCardId`	推播至卡匯款，以原始入帳交易（OCT）方式送達。僅適用於符合資格的金融卡。將 `isExpedited: true` 設為即時入帳，或省略以使用標準時程結算。可能產生費用。
`PAYPAL`	`paypalVaultId`	匯款至已連結的 PayPal 帳戶。可能產生費用。
`VENMO`	`venmoAccountId`	匯款至已連結的 Venmo 帳戶。可能產生費用。

Preview Fees Before Withdrawing

使用 getWithdrawFeeEstimate 查詢在提交前為提領報價。傳入你打算使用的相同 amount、method、source 與 isExpedited，回應會告知使用者實際可收到的金額。

{
  "query": "query getWithdrawFeeEstimate($input: GetWithdrawFeeEstimateInput!) { getWithdrawFeeEstimate(input: $input) { fee netAmount feePercent feeMaxCap settlementDelayDays } }",
  "variables": {
    "input": {
      "amount": 100.00,
      "method": "BANK_CARD",
      "source": "CASH_BALANCE",
      "isExpedited": true
    }
  }
}

Field Name	Type	Description
`fee`	`Float!`	本次提領將收取的費用。
`netAmount`	`Float!`	扣除費用後，使用者實際可收到的金額。
`feePercent`	`Float!`	套用的費率百分比。
`feeMaxCap`	`Float`	如適用，費用的美元上限。
`settlementDelayDays`	`Int`	結算所需的工作天數。對於即時結算的加速提領為 `null`。

費用是自提領金額中扣抵，而非加在金額上：餘額會被扣除完整的 amount，目的地則收到 netAmount。將 FLUZPAY 作為 method 會回傳 ARG-0001。

Push-to-Card Withdrawals (OCT)

BANK_CARD 提領屬於推播至卡的付款，並以**原始入帳交易（OCT）**的卡網路交易型態將資金入帳至卡片。此方式需要 bankCardId，且所連結的金融卡必須支援 OCT。不符合資格的卡無法以其他方式送達，使用者需改選其他提領方式。 以 isExpedited 控制入帳速度：

`isExpedited`	Behavior
`true`	資金會在請求期間即時推送至卡片。
`false` 或省略	提領會以 `PENDING` 紀錄，並於 `settlementDelayDays` 個工作天後釋出。

PENDING 的推播至卡提領尚未定案。標準提領會在結算延遲後才入帳至卡片，屆時仍可能失敗——例如該卡已無法接收款項。若失敗，資金會退回來源餘額。請對提領狀態進行對帳，而非將初次 PENDING 回應視為已完成的付款。

Card Eligibility

多數 Visa 與 Mastercard 金融卡可接收推播至卡的付款。資格會在提交提領時評估，這是卡片本身的屬性，而非可由你設定。

資格無法事先得知，且與入金資格互不相干。目前沒有查詢可回報卡片是否支援 OCT——會在首次對該卡進行提領時才顯示。提領與入金的資格也彼此獨立，因此使用者可成功入金的卡片，不一定能用於提領。請參考自外部帳戶入金。

BANK_CARD 提領不受 cardType 限制：PREPAID 卡不會被預先排除，會如同其他卡片一樣以資格審核決定接受或拒絕。由於 BANK_CARD 沒有替代的送達路徑，請務必在你的介面中保留 BANK_ACH、PAYPAL 或 VENMO 的可達性，避免因卡片不符合資格而中斷流程。推播至卡失敗會以 HN-0124 或 BC-0004 呈現——請見下方的錯誤處理。

Error Handling

常見錯誤情境：

Error Code	Description
`WDR-0001`	餘額不足——使用者的資金不足以完成提領。
`WDR-0002`	金額無效——金額為零或負數。
`WDR-0003`	一般提領錯誤。請檢查錯誤訊息以瞭解詳情。
`WDR-0004`	無效的提領方式——請使用 `PAYPAL`、`BANK_ACH`、`BANK_CARD` 或 `VENMO`。
`WDR-0005`	無效的 Venmo 手機號碼。適用於 `VENMO` 提領。
`WDR-0006`	該 Venmo 帳戶已連結。適用於 `VENMO` 提領。
`WDR-0007`	已超過此付款方式的提領上限。
`ARG-0001`	必填參數無效。將 `FLUZPAY` 傳入 `getWithdrawFeeEstimate` 也會回傳此代碼。
`ARG-0002`	缺少必填參數——`idempotencyKey`、`amount`、`method`，或所選方式的目的地 ID。
`HN-0124`	該卡不符合推播至卡（OCT）提領資格。請提供其他方式。
`BC-0004`	該卡被拒。請顯示訊息並提供其他方式。
`G-0004`	目前暫停銀行卡提領服務。請稍後再試或改用其他方式。

ARG-* 錯誤會在任何資金移動之前拋出。

Example Error Response

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

Multiple Withdrawals

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

{
  "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 查詢以確認使用者有足夠資金再發起提領。
處理處理中（pending）狀態 - 提領可能需要時間處理。status 欄位會指出提領目前的狀態。
保存交易參考 - 儲存 withdrawId 與 transactionLogId 以利對帳與客服支援。

Changelog

v1.3.0

加速提領與費用預覽

重新引入 WithdrawCashBalanceInput 的 isExpedited。它控制 BANK_CARD 提領的入帳速度：true 於請求期間立即推送至卡；false 或省略則採標準時程結算。這取代了下方 v1.2.0 的說明（當時表示該欄位已移除）。
新增 getWithdrawFeeEstimate 查詢與 GetWithdrawFeeEstimateInput / WithdrawFeeEstimate 型別，可在提交前預覽費用、淨額與結算時間。
補充說明推播至卡為原始入帳交易（OCT），包含卡片資格，以及標準提領在提交後仍可能失敗並退回來源餘額的情況。
更正 withdrawCashBalance 所需的 scope 為 MAKE_WITHDRAWAL。本頁先前列示的 MANAGE_PAYMENT 有誤；Withdraw 型別上的 seat_id 亦為選填（UUID），並非 v1.2.0 所述必填。
說明 FLUZPAY 雖存在於 WithdrawMethods 列舉中，但不可用作提領方式：withdrawCashBalance 會以 WDR-0004（無效的提領方式）拒絕，getWithdrawFeeEstimate 會以 ARG-0001 拒絕。

v1.2.0 - 2024-11-20

Schema 微調與欄位清理

自 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 scope
新增 WithdrawMethods 列舉，包含 PAYPAL、BANK_ACH 與 BANK_CARD 方式
新增 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

​Preview Fees Before Withdrawing

​Push-to-Card Withdrawals (OCT)

​Card Eligibility

​Error Handling

​Example Error Response

​Multiple Withdrawals

​Best Practices

​Changelog

​v1.3.0

​v1.2.0 - 2024-11-20

​v1.1.0 - 2024-10-15

​v1.0.0 - 2024-09-01

Overview

Withdraw Cash Balance

Sample Request

Input Fields

WithdrawCashBalanceInput

Sample Response

Response Fields

Withdraw Object

Required Scope

Withdrawal Methods by Account Type

Preview Fees Before Withdrawing

Push-to-Card Withdrawals (OCT)

Card Eligibility

Error Handling

Example Error Response

Multiple Withdrawals

Best Practices

Changelog

v1.3.0

v1.2.0 - 2024-11-20

v1.1.0 - 2024-10-15

v1.0.0 - 2024-09-01