Beneficiaries

Manage trusted transfer recipients

All endpoints on this page require a valid Authorization: Bearer <token> header. Requests without a valid token return 401 Unauthorized.

Saving a beneficiary improves risk scoring. Subsequent transfers to a saved beneficiary receive a lower risk score from the risk assessment model.

List beneficiaries

GET /api/ledger/beneficiaries

Returns all saved beneficiaries for the authenticated user.

Response

id · string · required

Unique beneficiary identifier (UUID).

name · string · required

Beneficiary’s full name.

alias · string

Friendly name for quick identification.

accountNumber · string · required

Beneficiary’s account number (CLABE or other identifier).

bankName · string · required

Name of the beneficiary’s bank.

isFavorite · boolean · required

Whether the beneficiary is marked as a favorite.

curl

curl --request GET \
  --url http://localhost:5000/api/ledger/beneficiaries \
  --header 'Authorization: Bearer <token>'

Response

[
  {
    "id": "ben-uuid",
    "name": "Juan Pérez",
    "alias": "Juan",
    "accountNumber": "646180987654321098",
    "bankName": "BBVA",
    "isFavorite": false
  }
]

---

Add beneficiary

POST /api/ledger/beneficiaries

Saves a new trusted recipient for the authenticated user.

Request body

name · string · required

Beneficiary’s full name.

accountNumber · string · required

Beneficiary’s account number (CLABE or other identifier).

bankName · string · required

Name of the beneficiary’s bank.

alias · string

Optional friendly name for the beneficiary.

Error responses

Status	Description
400	Validation error — name, accountNumber, and bankName are required.
401	Invalid or missing bearer token.

curl

curl --request POST \
  --url http://localhost:5000/api/ledger/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Juan Pérez",
  "accountNumber": "646180987654321098",
  "bankName": "BBVA",
  "alias": "Juan"
}'

Response (201 Created)

{
  "id": "ben-uuid",
  "name": "Juan Pérez",
  "alias": "Juan",
  "accountNumber": "646180987654321098",
  "bankName": "BBVA",
  "isFavorite": false
}

---

Remove beneficiary

DELETE /api/ledger/beneficiaries/{id}

Permanently removes a saved beneficiary. Only the owning user can delete their own beneficiaries.

Path parameters

id · string · required

UUID of the beneficiary to delete.

Response

Returns 204 No Content on success with an empty body.

Error responses

Status	Description
401	Invalid or missing bearer token.
404	Beneficiary not found, or it belongs to a different user.

curl

curl --request DELETE \
  --url http://localhost:5000/api/ledger/beneficiaries/ben-uuid \
  --header 'Authorization: Bearer <token>'