External payouts

​

Overview

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

1. Save the recipient’s bank account as a payee with createExternalPayee.
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.

• createExternalPayout - Send money to an external payee

​

createExternalPayout

​

Mutation (CreateExternalPayoutInput)

createExternalPayout(input: CreateExternalPayoutInput!): ExternalPayoutResult

​

Input

​

Response (ExternalPayoutResult)

​

Example

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

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

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

​

Error Codes

​

Payout status

​

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.