The Beneficiary object
The shape of a beneficiary wherever the API returns one.
Every endpoint that returns a beneficiary returns this shape, wrapped in a data envelope.
Attributes
id
uuid · always presentWhat you pay this destination by.
type
enum · always present— One of: bank, mobile_money, paybill, paytill.
country
string · always present—
currency
string · always present—
account_masked
string · always presentLast four digits only. The full number is never published here - a key has no human and no second factor behind it.
label
string · optionalYour own note, set when you saved it. With the number masked and no name published, this is how you tell two destinations apart - so it is worth setting.
bank_code
string · optionalThe institution code for banks, or the operator network for the mobile-money family.
business_code
string · optionalThe second routing identifier, set only for types that need one - the M-Pesa paybill shortcode today.
name_verified
boolean · always presentWhether the account holder's name was confirmed by name enquiry. Where false, the name we hold was typed rather than checked against the account - on corridors with no lookup that is every destination, so it describes our confidence, not this row being unusual.
usable
boolean · always presentWhether this destination can be paid NOW. A newly saved destination spends a cooling-off window unusable; paying one before it opens is refused, so read this rather than discovering it at submit.
usable_at
timestamp · optionalWhen the cooling-off window closes. Present ONLY while usable is false - once the window has passed it would be noise on every row.
created_at
timestamp · always present—
{
"id": "0d6c2f3a-1b4e-4c9a-9f2d-7a1e5c8b3d60",
"type": "bank",
"country": "GH",
"currency": "GHS",
"account_masked": "**** 3456",
"label": "<label>",
"bank_code": "MTN",
"business_code": "<business_code>",
"name_verified": "<name_verified>",
"usable": "<usable>",
"usable_at": "2026-09-01T10:04:11Z",
"created_at": "2026-09-01T10:04:11Z"
}Beneficiaries
The payout destinations this project has saved.
Fetch a beneficiary
The other half of the join: a payment row publishes `destination.id`, and this is where that id resolves. A destination that is not yours is a 404, never a 403. A destination you have since REMOVED is also a 404 - the payment itself still carries the masked account, which is the durable record of where the money went.