> ## 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 将资金从已认证用户的某个现金余额发送给外部收款人。

#### 变更（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 不提供在付款创建后查询其状态的接口。

***

### 重要说明

#### 资金与时效

* 变更成功后，现金余额会立即扣除 `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.