Skip to main content
A Beneficiary is a person or business your Business pays. Before a payout can name them, three things must be true: their identity is on file, their compliance status is compliant, and they have a payout_usable bank account. This page explains how each of those comes about, and the two different paths that get you there.

​
Two onboarding paths

You enter the details. If you already hold the beneficiary’s identity and bank details, create them directly and register their bank account. This is the path the quickstart walks. The beneficiary enters their own. Send a collection invite and Cleff emails the beneficiary a secure link to a Cleff-hosted form where they submit their own profile and bank details. This keeps the most sensitive data (bank account numbers, tax details) out of your systems entirely. Both paths are batch-capable: collection invites accept 1..N beneficiaries in one call, and bulk invites accept up to 500 CSV-shaped rows, creating an identity stub per row and inviting each one. The dashboard’s invite buttons drive these same endpoints.
  • Each link carries a scope, which is what the form may collect: a full onboarding, just new bank details, or tax documents. It authorizes only that submission; it is not a login and grants no standing access.
  • Links expire after 7 days. Re-inviting issues a fresh link and invalidates the prior one; you can also cancel a live request outright.
  • Live links are visible as pending_requests on the beneficiary, and submission is observable via collection_status and details_submitted_at.
  • Invite emails render in your Business’s brand if you have configured one (dashboard Settings → Company → Brand), always with a “Powered by Cleff” attribution, and with a sandbox banner when sent from sandbox.

​
The compliance attestation

Payout creation requires the beneficiary to be compliant. Compliance is KYC for a person and KYB for a business, and in the current model it is your Business that attests to it: passing acknowledged: true at creation, or calling acknowledge compliance later, records that your Business has independently verified the beneficiary’s identity and moves them pending → compliant, stamping acknowledged_at. Editing a PII trigger field (legal name, date of birth, tax id, country) after acknowledgment sets reacknowledgment_required; re-acknowledge to clear it before the next payout. Cleff can also place a beneficiary in suspended, which blocks payouts until the hold is lifted. The schema is shaped so that provider-verified compliance can replace the attestation model without breaking your integration.

​
Bank accounts

Bank accounts are a sub-resource of the beneficiary, and payouts name one explicitly; a beneficiary can hold several (different currencies, a replacement after a failed payout). Three independent checks fold into the one flag worth reading, payout_usable:
  1. Verified: the account belongs to a compliance-acknowledged beneficiary. Registration against an already-compliant beneficiary verifies immediately.
  2. Validated: the routing details pass Cleff’s format checks (US ABA checksum, IBAN mod-97 for IBAN corridors).
  3. Not rail-rejected: the payout rail has not refused the account. A rejection reason, when present, is surfaced as rail_rejection_reason.
Account identifiers are encrypted at rest and masked to last4 in every response; the full number is never serialized back. If a payout is refused because of the destination account, the error catalogue names the exact check that failed and the resolving action.