Receivables

Payouts and processor fees

Record each card or ACH payout so its fees land in the books.

Record a payout

Scope: payments:write. Payments are recorded at their full amount into a clearing account. When the processor pays out, send the payout: HelloLedger posts the fee (debit the fee expense, credit clearing). What's left in clearing equals the net deposit, which the bookkeeper matches to the bank feed. The deposit itself isn't posted here, so it's never counted twice.

PUT

curl -X PUT "https://api.helloledger.ai/v1/companies/{company_id}/payouts/by-external-id/po_1QxYz" \
  -H "Authorization: Bearer $HL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "date": "2026-10-06",
  "clearing_account_id": "66f1a2b3c4d5e6f708091c3d",
  "gross": "2550.00",
  "fee": "74.25",
  "net": "2475.75",
  "fee_account_id": "66f1a2b3c4d5e6f708092182",
  "bank_account_id": "66f1a2b3c4d5e6f708091e5f",
  "reference": "po_1QxYz",
  "payment_external_ids": [
    "pay_pi_3Q8x",
    "pay_pi_3Q8y",
    "pay_pi_3Q8z"
  ]
}'

Response

{
  "payout_id": "66f8…",
  "external_id": "po_1QxYz",
  "date": "2026-10-06",
  "clearing_account_id": "66f1a2b3c4d5e6f708091c3d",
  "bank_account_id": "66f1a2b3c4d5e6f708091e5f",
  "fee_account_id": "66f1a2b3c4d5e6f708092182",
  "gross": "2550.00",
  "fee": "74.25",
  "net": "2475.75",
  "reference": "po_1QxYz",
  "memo": null,
  "payment_external_ids": ["pay_pi_3Q8x", "pay_pi_3Q8y", "pay_pi_3Q8z"],
  "status": "posted",
  "result": "created"
}

Fields

Field	Type	Notes
date	YYYY-MM-DD, required	Payout date. The fee posts on this date.
clearing_account_id	string, required	The clearing account the payments went to.
gross, fee, net	decimal strings, required	net must equal gross minus fee. fee can be 0.
fee_account_id	string	Expense account for the fees. Required when fee is above 0.
bank_account_id	string	Where the payout landed. Stored for reference; not posted.
payment_external_ids	array of strings	Optional. The payments in this payout, for reconciliation.
reference, memo	string	Optional. Use the processor's payout ID as the reference.

Rules

Payouts can't be edited. Void one and send the corrected payout under a new external ID.
Voiding a payout removes its fee entry.
Refunds and chargebacks taken out of a payout are recorded on their own (refunds, or voiding the payment); the payout's gross and fee are what the processor reports.

POST

curl -X POST "https://api.helloledger.ai/v1/companies/{company_id}/payouts/by-external-id/po_1QxYz/void" \
  -H "Authorization: Bearer $HL_API_KEY"

GET

curl "https://api.helloledger.ai/v1/companies/{company_id}/payouts/by-external-id/po_1QxYz" \
  -H "Authorization: Bearer $HL_API_KEY"