Beneficiaries & compliance

Understand who you can pay and where their money lands. For developers deciding how to onboard the people they pay and how to create payouts to them. A Beneficiary (the payee) is a person or business your Business pays. A payout to a Beneficiary is accepted only when three things are true:

1. Your Business has attested to their compliance, so their compliance_status is compliant.
2. They hold a destination that can be paid: a bank account or a debit card.
3. The payout resolves to exactly one of their destinations: the declared one, the one you name, or the only one they hold.

Each of these is covered below. To do it step by step, follow Onboard a Beneficiary.

​

Attest to a Beneficiary’s compliance

Compliance is KYC for a person and KYB for a business. Your Business attests to it: passing acknowledged: true when you create the Beneficiary, or calling acknowledge compliance later, records that you have independently verified who they are. The Beneficiary moves from pending to compliant, and acknowledged_at is stamped. Editing an identity field after you acknowledge sets reacknowledgment_required: the legal name, tax id, and for a person the date of birth and country of residence, or for a business the registration number and country of incorporation. The Beneficiary stays compliant, but new payouts to them are refused until you acknowledge them again. The API is shaped so that verified compliance can later replace the attestation without breaking your integration.

​

Read the Beneficiary status

status on every Beneficiary names the single most pressing thing standing between you and paying them. It is computed on every read from their compliance, their identity details and their destinations. ready means nothing on the Beneficiary blocks a payout; which destination the payout goes to, and whether that one can be paid, is decided when you create it, as described below. Archiving is separate from status. An archived Beneficiary has archived_at set, drops out of your list and export, and refuses new payouts. Archiving can’t be undone: create the Beneficiary again to pay them.

​

Give a Beneficiary somewhere to be paid

A destination is somewhere a payout can land. A Beneficiary can hold several, of two kinds: The Beneficiary types a card into a secure form hosted for them, so the card number never reaches your systems or Cleff’s API. The dashboard’s Settings → Plan & Billing page shows whether your Business can pay cards. List a Beneficiary’s destinations to see both kinds. The endpoint is named for bank accounts, but each item carries kind, and cards appear alongside banks. Account and card numbers are masked to last4 in every response; the full number is never returned. Each item also carries what a picker needs, all masked: name, a label such as Chase USD ••1234 checking or Card ••1234 · exp 08/27; bank_name, when one was sent at registration; and card_valid_through, the last day a card is valid, in UTC.

​

Check that a destination can be paid

Each destination carries payout_usable, the one flag worth reading. It is true only when every check below passes: A destination that needs replacing can’t be used again, and Cleff never pays another of the Beneficiary’s destinations in its place. The error catalogue carries the full text of each code. Registering a bank account refuses anything other than a US bank in USD up front, with BANK_ACCOUNT_VALIDATION_FAILED, so nothing unpayable is saved.

​

Know which destination a payout goes to

A Beneficiary can choose where they want to be paid. The destination they pick in a collection link becomes their declared destination, shown as declared_destination_id on the Beneficiary. You can set it too, to any of their destinations that can be paid, with set the declared destination. The last write wins, and Cleff emails the Beneficiary when you change it, naming the account their payouts now default to. Registering a bank account on their behalf leaves it alone. When you create a payout, destination_id is optional. Naming one pays that destination, whether or not it is the declared one, and the declaration doesn’t change: it is the default for a payout that names none, not a lock. Which destination a payout goes to depends on what you send and on whether the Beneficiary has declared one: “Hold” counts destinations that are verified, validated and in date, including one the provider refused. So a Beneficiary with one good bank account and one refused one holds two, and a payout that names neither is ambiguous. A refused payout creates nothing, so it is safe to correct and resend. The destination list marks the answer with default. It is true on the destination a payout that names no destination_id goes to: the declared destination, else the only one they hold. When they hold several and have declared none, no item is the default. A default can still have payout_usable: false, for example a declared card that has expired: the payout is refused, never sent to another destination, so read payout_usable as well. A payout keeps the destination it resolved to when you created it. If the declared destination changes afterwards, their next payout goes there; the one already created does not move.

​

Delete a destination

Delete a destination that is wrong or no longer wanted, a bank account or a card. A destination’s details are fixed when it is registered, so a wrong one is replaced by deleting it and registering the correct one. A deleted destination can’t be paid or chosen. It leaves the destination list and the Beneficiary’s collection link, and a payout that names it is refused. A card you delete does not come back through the Beneficiary’s next card collection. Payouts already created to it are not moved: If the destination was the Beneficiary’s declared destination, declared_destination_id becomes null and Cleff emails the Beneficiary to say the account was removed. A payout that names no destination_id then goes to the only destination they hold that can be paid, or is refused as for any Beneficiary with none declared. Deleting a destination that is already deleted succeeds and changes nothing.

​

Change a Beneficiary’s email

Update a Beneficiary can’t change the email of a Beneficiary who has a destination on file, whoever registered it: their collection link goes to that address, and moving it would let you complete their own steps for them. The request is refused with BENEFICIARY_EMAIL_LOCKED. Sending the email they already have is not a change, in any letter case, so a full-replace update keeps working. To correct it, delete their destinations, update the email, and register the bank accounts again. A card comes back through their own link, which goes to the new address.

​

Choose how to onboard

There are three ways to get a Beneficiary to ready. Which one fits depends on what you already hold: Import is the only path that lands a Beneficiary ready to pay in a single request. Inviting keeps the most sensitive details, account and card numbers and tax details, out of your systems entirely, and it is the only way a Beneficiary can add a card or declare a destination. Onboard a Beneficiary walks all three.

​

Send a collection link

A collection invite emails a Beneficiary a secure link to a Cleff-hosted form. They pick the kind of destination themselves, so you never need to know whether they would rather be paid to a bank or a card, and one who already holds a destination can pick it instead of entering a new one.

• A link authorizes one submission for one Beneficiary. It is not a login and grants no standing access.
• Links expire after 7 days. Inviting again issues a fresh link and invalidates the previous one; you can also cancel a live request.
• Invite emails carry 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.

A submitted identity still needs your attestation: the Beneficiary stays pending_kyc until you acknowledge compliance.

​

Next steps