> ## 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.

# 外部付款

用於透過 ACH 將資金從 Fluz 現金餘額匯至已儲存的外部收款人的銀行帳戶。

### 總覽

外部付款會將資金**轉出 Fluz**，匯入屬於他人的美國銀行帳戶，例如承包商、供應商或朋友。收款方不需要擁有 Fluz 帳戶。

為什麼使用外部付款：

* **向任何擁有美國銀行帳戶的人付款。** 收款方只需要路由號碼和帳號，不必註冊 Fluz。
* **直接從你的 Fluz 餘額付款。** 資金來自帳戶的某個現金餘額，因此不需要另外的儲值步驟。
* **可安全重試。** 每筆付款都帶有冪等鍵，因此網路重試絕不會重複轉出資金。
* **費用一目了然。** 回應會顯示手續費以及從餘額中扣除的總額。

運作方式：

1. 使用 [`createExternalPayee`](https://docs.fluz.app/features/external-payees) 將收款方的銀行帳戶儲存為收款人。
2. 使用收款人、來源現金餘額和金額呼叫 `createExternalPayout`。
3. Fluz 會立即扣除現金餘額，並回傳狀態為 `PENDING` 的付款。
4. 資金將在下一個標準 ACH 檔案中傳送到收款方的銀行。

一個操作用於傳送付款：

* `createExternalPayout` - 向外部收款人轉帳

> [!NOTE]
>
> 外部付款用於向**他人**的銀行帳戶轉帳。若要將資金轉入使用者本人的銀行帳戶，請使用 [提領](https://docs.fluz.app/features/move-funds-with-external-accounts.md)。若要向另一個 Fluz 帳戶轉帳，請使用 [帳戶對帳戶轉帳](https://docs.fluz.app/features/account-to-account-transfers.md)。

***

### createExternalPayout

透過 ACH 將資金從已驗證使用者的某個現金餘額匯給外部收款人。

#### Mutation（CreateExternalPayoutInput）

```graphql theme={null}
createExternalPayout(input: CreateExternalPayoutInput!): ExternalPayoutResult
```

**需要**：`MAKE_PAYOUT_TRANSFER_SEND` 範圍。

#### 輸入

| 欄位 | 類型 | 必填 | 說明 |
| :- | :- | :- | :- |
| idempotencyKey | UUID! | 是 | 此筆付款的唯一鍵。僅在重試同一個請求時才重複使用同一個鍵。 |
| externalPayeeId | UUID! | 是 | 要付款的收款人。必須屬於已驗證使用者的帳戶。 |
| sourceCashBalanceId | UUID! | 是 | 要扣款的現金餘額。必須屬於已驗證使用者的帳戶且處於啟用狀態。 |
| amount | Float! | 是 | 收款人收到的金額，以美元計。必須大於 0，最多兩位小數。手續費在此金額之外另行收取。 |

#### 回應（ExternalPayoutResult）

| 欄位 | 類型 | 說明 |
| :- | :- | :- |
| transferId | ID! | 付款 ID |
| externalPayeeId | ID! | 已收款的收款人 |
| amount | Float! | 收款人收到的金額 |
| fee | Float! | 在金額之外收取的手續費 |
| totalDebited | Float! | `amount + fee`。從來源現金餘額中扣除的總額。 |
| status | ExternalPayoutStatus! | 付款建立時一律為 `PENDING` |

#### 範例

```graphql theme={null}
mutation {
  createExternalPayout(
    input: {
      idempotencyKey: "550e8400-e29b-41d4-a716-446655440020"
      externalPayeeId: "3f1c2b7e-8d4a-4c1e-9f2a-6b5d4e3c2a10"
      sourceCashBalanceId: "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee"
      amount: 100.00
    }
  ) {
    transferId
    externalPayeeId
    amount
    fee
    totalDebited
    status
  }
}
```

**成功：**

```json theme={null}
{
  "data": {
    "createExternalPayout": {
      "transferId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "externalPayeeId": "3f1c2b7e-8d4a-4c1e-9f2a-6b5d4e3c2a10",
      "amount": 100,
      "fee": 1.5,
      "totalDebited": 101.5,
      "status": "PENDING"
    }
  }
}
```

*此範例中的手續費僅供示範。請一律以回應中回傳的 `fee` 和 `totalDebited` 值為準。*

**餘額不足：**

```json theme={null}
{
  "errors": [
    {
      "message": "The sender does not have sufficient balance to complete this transfer.",
      "extensions": { "code": "PT-0007" }
    }
  ]
}
```

#### 錯誤碼

| 代碼 | 說明 |
| :- | :- |
| ARG-0002 | 缺少必填欄位，或 `amount` 不大於 0 |
| ARG-0001 | 輸入無效。例如：`idempotencyKey` 不是 UUID、找不到收款人或該收款人無法用於付款、來源現金餘額未啟用，或該冪等鍵已用於另一個不同的請求。 |
| PT-0001 | 超出每日付款上限 |
| PT-0002 | 超出每週付款上限 |
| PT-0003 | 超出每月付款上限 |
| PT-0004 | 超出每年付款上限 |
| PT-0005 | 金額低於最低付款金額 |
| PT-0006 | 金額高於最高付款金額 |
| PT-0007 | 餘額不足以支付金額加手續費 |
| PT-0008 | 部分餘額仍在清算中。請降低金額後重試。 |
| G-0003 | 此帳戶未啟用向外部銀行帳戶轉帳的功能，或無法授權該筆付款 |
| G-0004 | 無法完成該筆付款 |
| G-0001 | 伺服器錯誤 |

***

### 付款狀態

`ExternalPayoutStatus` 列出了付款的所有可能狀態。

| 狀態 | 說明 |
| :- | :- |
| PENDING | 付款已建立，餘額已扣除。資金尚未離開 Fluz。 |
| PROCESSING | 付款正在處理中 |
| COMPLETED | 付款已完成 |
| FAILED | 付款失敗 |
| FAILED\_INITIAL | 付款在首次提交時失敗 |
| CANCELED | 付款在傳送前已被取消 |
| REFUNDED | 付款金額已退回現金餘額 |
| RETURNED | 收款方的銀行退回了該筆付款 |

`createExternalPayout` 一律回傳 `PENDING`。目前 API 不提供在付款建立後查詢其狀態的介面。

***

### 重要事項

#### 資金與時效

* mutation 成功後，現金餘額會立即扣除 `totalDebited`。
* 付款使用標準 ACH。不支援當日 ACH 和加急 ACH。
* 資金會在下一個 ACH 檔案中離開 Fluz。到帳所需時間取決於 ACH 處理以及收款方的銀行。

#### 費用與上限

* 手續費由 Fluz 設定，並在 `amount` 之外另行收取。收款方會收到完整的 `amount`。
* 每日、每週、每月和每年的上限，以及最低和最高金額，均按帳戶適用。達到上限時，請求會失敗並回傳 `PT-` 錯誤碼。
* 仍在清算中的資金無法傳送。

#### 冪等性

* 每筆新付款都傳送一個新的 UUID。
* 如果請求逾時，請使用**相同**的鍵和相同的輸入重試。你會取得原始結果，且資金不會被重複轉出。
* 如果同一個鍵被用於不同的金額、來源餘額或收款人，請求將被拒絕。
* 冪等鍵在所有轉帳類型之間共用。已用於其他類型轉帳的鍵不能在此處重複使用。

#### 收款人

* 收款人必須在帳戶上處於啟用狀態。已移除的收款人無法收款。
* 部分銀行帳戶無法接收付款。此時請求會失敗並回傳 `ARG-0001`。

#### 遭退回的付款

* 如果收款方的銀行拒收該筆付款（例如帳戶已關閉），資金會退回到來源現金餘額。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.