Skip to main content
GET
Get a Payout
Agents: fetch this page as plain markdown at https://docs.usecleff.com/api-reference/payouts-get.md.

Authorizations

Authorization
string
header
required

Cleff API key, created in the dashboard under Settings → API keys

Path Parameters

payoutId
string
required

Response

id
string
required
state
enum<string>
required

The full lifecycle step. Read it when you need the exact step, such as compliance_hold or settled; to decide what to do next, branch on status.

Available options:
pending_approval,
approved,
rejected,
disbursed,
failed,
returned,
canceled,
settled,
compliance_hold
status
enum<string>
required

Where the payout stands, in terms of what you do next. Derived from state and delivered_at, so it moves when they do. needs_approval: approve or reject it. processing: approved and being sent, including a pause for review. in_transit: the money has left your Cleff Account and has not arrived. delivered: the money has arrived in the Beneficiary's account; a late return can still follow. rejected, canceled, failed and returned: the payout ended without the payee being paid, though a failed payout with failure_code indeterminate may have moved the money.

Available options:
needs_approval,
processing,
in_transit,
delivered,
rejected,
failed,
returned,
canceled
delivered_at
string<date-time> | null
required

When the money arrived in the Beneficiary's account. Null until it does, and stays set if the payout is later returned.

beneficiary_id
string
required
destination_id
string<uuid> | null
required

Where the money goes, pinned when the Payout was created. A later change to the Beneficiary's declared destination does not move it. Null only on Payouts created before destinations were recorded.

destination_kind
enum<string> | null
required
Available options:
bank,
card
bank_account_id
string<uuid> | null
required
deprecated

Deprecated: read destination_id. Set only when the destination is a bank account, so it never carries a card's id.

amount_minor
number
required
purpose_of_payment
enum<string>
required

Why the funds were sent. Provisional corridor-agnostic set.

Available options:
advertising,
advisor_fees,
charity,
education,
family_support,
investment,
loan_repayment,
medical,
other,
payroll,
purchase_of_goods,
purchase_of_services,
real_estate,
royalties,
taxes,
treasury,
travel
currency
string
required
external_ref
string | null
required
idempotency_key
string
required
validator_strategy
enum<string>
required
Available options:
manual
environment
enum<string>
required
Available options:
sandbox,
production
provider
string | null
required

Who carried the Payout for Cleff. Opaque: quote it to Cleff support, but never branch on it, because its values change without notice.

provider_payout_id
string | null
required

The reference provider gave the Payout. Opaque, like provider.

rail
enum<string> | null
required

The network that carried the payment, as the provider reported it: ach, rtp, fednow or card. Null until the provider reports one, and for a payout that never reached the provider.

Available options:
ach,
rtp,
fednow,
card
rail_ref
string | null
required
replaces_payout_id
string | null
required
failure_code
enum<string> | null
required

Why the money did not move. Null until a Payout fails, and on rows that failed before the reason was recorded. indeterminate means Cleff does not know the provider's answer, which is not the same as a rejection.

Available options:
insufficient_funds,
business_not_enrolled,
account_closed,
account_invalid,
account_frozen,
account_unauthorized,
account_not_enrolled,
indeterminate
failure_detail
string | null
required

The rail's own words for the failure, for a human to read. Never branch on it — the vocabulary is the provider's and it changes without notice.

fault
enum<string> | null
required

Whose problem the failure is, resolved from failure_code. Route on this before refining to the code itself.

Available options:
business,
destination_account,
unknown
replaceable
boolean
required

Whether this Payout can be answered with a replacement. False once one exists, and false for an indeterminate failure, where the money may already have moved.

created_at
string<date-time>
required
beneficiary_name
object | null
beneficiary_type
enum<string> | null
Available options:
person,
business
via
object | null

Channel through which the Intent arrived.