Beneficiaries

A beneficiary is a recipient your organisation pays: a person or a business, together with the bank account that receives the money. Stables keeps every beneficiary you pay so you can pay them again without re-entering their details.

Beneficiaries belong to your organisation, not to a customer. Any of your customers can pay any of your beneficiaries; each transfer decides who is paying and how much.

---

What a beneficiary holdsCopy Anchor Link

Each beneficiary is bound to the currency it receives and the network it is paid by (bank for a local transfer, swift for an international wire). Together these decide which details the beneficiary needs. See Beneficiary Requirements for the fields each currency asks for.

A beneficiary keeps:

• Who is being paid: the account holder's name and, where the currency asks for it, recipient type, date of birth, address and phone.
• Where the money lands: the account number or IBAN, bank details and bank codes.
• How you refer to it: an optional label, shown in place of the account holder's name in the dashboard.

Per-payout information, such as supporting documents and logistics tracking details, belongs to a single transfer. It is never stored on the beneficiary.

---

How beneficiaries are createdCopy Anchor Link

You don't have to create beneficiaries up front.

• From transfers. Every bank transfer saves its destination as a beneficiary automatically, whether you pay with inline bank details or by reference. Every recipient you have paid appears in your beneficiaries list.
• Ahead of time. You can also save a beneficiary before paying it, through the API or the dashboard. The details are checked exactly as a transfer on that network would check them, so a beneficiary that saves successfully is ready to pay.

One beneficiary per accountCopy Anchor Link

Stables recognises a beneficiary by the details that decide which account the money reaches: the account holder's name, the account identifiers and bank codes, the currency and the network.

• Saving an account you already have returns the existing beneficiary instead of a duplicate. Its contact details (address, phone, date of birth, recipient type, bank name) are refreshed with what you sent.
• Changing the account itself, such as a different account number, a different holder or a different network, is a different beneficiary.

So the same account paid by local transfer and by SWIFT is two beneficiaries, one per network.

---

Paying a beneficiaryCopy Anchor Link

To pay a saved beneficiary, create a transfer with a beneficiary destination and its beneficiary_id instead of inline bank details. Stables fills in the stored recipient and bank details, then validates and routes the transfer exactly as if you had sent those details yourself. The quote's currency and network must match the beneficiary's.

Per-payout extras, such as supporting documents, are still sent with the transfer.

Every bank transfer returns the beneficiary_id of the beneficiary it paid, including transfers created with inline details. Use it to link a payment back to the recipient in your own records.

---

Keeping details currentCopy Anchor Link

Payout rules change over time. A currency can start asking for details it didn't need before, such as the enhanced beneficiary details. A beneficiary saved earlier can therefore become incomplete.

Every beneficiary carries a validation result that checks its stored details against today's rules:

• When valid is true, the beneficiary can be paid as it is.
• When valid is false, the errors list what is missing or no longer accepted. Save the beneficiary again with the missing details; this completes the existing beneficiary rather than creating a new one.

---

ArchivingCopy Anchor Link

Archiving is the only change you make to a beneficiary directly. There is no edit: to correct details, save the beneficiary again.

An archived beneficiary:

• is hidden from active listings and from the transfer picker in the dashboard;
• is refused as a transfer destination;
• stays linked to every transfer already made to it, so your history is unaffected.

Saving the same account again restores an archived beneficiary. Paying the same account with inline bank details still works, and the transfer links to the archived beneficiary without restoring it.

---

What can't be a beneficiaryCopy Anchor Link

• Crypto destinations. Beneficiaries are bank accounts only.
• PayID aliases. A PayID is resolved for each payment, so it is never stored as a beneficiary.

---

ErrorsCopy Anchor Link

---

In the dashboardCopy Anchor Link

• Beneficiaries in the sidebar lists your organisation's beneficiaries with search and filters by currency, network and status. Each beneficiary has a detail page, where you can archive it.
• New transfer: the destination step asks whether you are paying an existing beneficiary or a new recipient. The beneficiary picker only offers beneficiaries that match the quote's currency and network.
• Transfer detail links to the beneficiary the transfer paid.

Viewing beneficiaries requires permission to view transfers. Saving and archiving them requires permission to create transfers. Read-only API keys can list and view beneficiaries but can't save or archive them.

---

API referenceCopy Anchor Link

• List Beneficiaries
• Save Beneficiary
• Get Beneficiary
• Archive Beneficiary
• Create Transfer, with a beneficiary destination