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

# External payouts

Used to send money from a Fluz cash balance to a saved external payee's bank account over ACH.

### Overview

An external payout moves money **out of Fluz** to a US bank account that belongs to someone else, for example a contractor, a vendor, or a friend. The recipient does not need a Fluz account.

Why use external payouts:

* **Pay anyone with a US bank account.** The recipient only needs a routing and account number. They do not sign up for Fluz.
* **Pay from your Fluz balance.** Funds come from one of the account's cash balances, so there is no separate funding step.
* **Safe to retry.** Every payout carries an idempotency key, so a network retry never sends the money twice.
* **Clear cost up front.** The response shows the fee and the total debited from the balance.

How it works:

1. Save the recipient's bank account as a payee with [`createExternalPayee`](https://docs.fluz.app/features/external-payees).
2. Call `createExternalPayout` with the payee, the source cash balance, and the amount.
3. Fluz debits the cash balance right away and returns the payout with status `PENDING`.
4. The money is sent to the recipient's bank in the next standard ACH file.

One operation sends payouts:

* `createExternalPayout` - Send money to an external payee

> [!NOTE]
>
> External payouts are for sending money to **other people's** bank accounts. To
> move money to the user's own bank account, use
> [withdrawals](https://docs.fluz.app/features/move-funds-with-external-accounts.md). To send money to
> another Fluz account, use [Account to Account
> Transfers](https://docs.fluz.app/features/account-to-account-transfers.md).

***

### createExternalPayout

Send money from one of the authenticated user's cash balances to an external payee over ACH.

#### Mutation (CreateExternalPayoutInput)

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

**Requires**: `MAKE_PAYOUT_TRANSFER_SEND` scope.

#### Input

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| idempotencyKey | UUID! | Yes | A unique key for this payout. Reuse the same key only when retrying the same request. |
| externalPayeeId | UUID! | Yes | The payee to pay. Must belong to the authenticated user's account. |
| sourceCashBalanceId | UUID! | Yes | The cash balance to debit. Must belong to the authenticated user's account and be active. |
| amount | Float! | Yes | The amount the payee receives, in USD. Greater than 0, at most two decimal places. The fee is charged on top. |

#### Response (ExternalPayoutResult)

| Field | Type | Description |
| :- | :- | :- |
| transferId | ID! | The payout ID |
| externalPayeeId | ID! | The payee that was paid |
| amount | Float! | The amount the payee receives |
| fee | Float! | The fee charged on top of the amount |
| totalDebited | Float! | `amount + fee`. The total taken from the source cash balance. |
| status | ExternalPayoutStatus! | Always `PENDING` when the payout is created |

#### Example

```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
	}
}
```

**Success:**

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

*The fee in this example is for illustration only. Always use the `fee` and `totalDebited` values returned in the response.*

**Insufficient balance:**

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

#### Error Codes

| Code | Description |
| :- | :- |
| ARG-0002 | A required field is missing, or `amount` is not greater than 0 |
| ARG-0001 | Invalid input. For example: `idempotencyKey` is not a UUID, the payee was not found or cannot be used for a payout, the source cash balance is not active, or the idempotency key was already used for a different request. |
| PT-0001 | Daily payout limit exceeded |
| PT-0002 | Weekly payout limit exceeded |
| PT-0003 | Monthly payout limit exceeded |
| PT-0004 | Yearly payout limit exceeded |
| PT-0005 | Amount is below the minimum payout amount |
| PT-0006 | Amount is above the maximum payout amount |
| PT-0007 | Not enough balance to cover the amount plus the fee |
| PT-0008 | Part of the balance is still clearing. Lower the amount and try again. |
| G-0003 | Sending money to external bank accounts is not enabled on this account, or the payout could not be authorized |
| G-0004 | The payout could not be completed |
| G-0001 | Server error |

***

### Payout status

`ExternalPayoutStatus` lists the possible states of a payout.

| Status | Description |
| :- | :- |
| PENDING | The payout was created and the balance was debited. The money has not left Fluz yet. |
| PROCESSING | The payout is being processed |
| COMPLETED | The payout is complete |
| FAILED | The payout failed |
| FAILED\_INITIAL | The payout failed when it was first submitted |
| CANCELED | The payout was cancelled before it was sent |
| REFUNDED | The payout amount was returned to the cash balance |
| RETURNED | The recipient's bank returned the payout |

`createExternalPayout` always returns `PENDING`. The API does not currently provide a query to check a payout's status after it is created.

***

### Important Notes

#### Funds and timing

* The cash balance is debited the `totalDebited` amount immediately when the mutation succeeds.
* Payouts use standard ACH. Same-day and expedited ACH are not available.
* Money leaves Fluz in the next ACH file. Arrival time depends on ACH processing and the recipient's bank.

#### Fees and limits

* The fee is set by Fluz and is added on top of `amount`. The recipient receives the full `amount`.
* Daily, weekly, monthly, and yearly limits, plus minimum and maximum amounts, apply per account. When a limit is reached, the request fails with a `PT-` error code.
* Funds that are still clearing cannot be sent.

#### Idempotency

* Send a new UUID for each new payout.
* If a request times out, retry with the **same** key and the same input. You get the original result back and the money is not sent twice.
* A key used with a different amount, source balance, or payee is rejected.
* Idempotency keys are shared across all transfer types. A key already used for another kind of transfer cannot be reused here.

#### Payees

* The payee must be active on the account. Removed payees cannot be paid.
* Some bank accounts cannot receive payouts. In that case the request fails with `ARG-0001`.

#### Returned payouts

* If the recipient's bank rejects the payout, for example because the account is closed, the money is returned to the source cash balance.


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