Transactions

Create and retrieve SPEI transactions

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

Before submitting a transaction, the frontend evaluates the transfer with POST /ai/risk. If the returned risk level is medium or high, the user is shown a ConfirmDialog before the transfer is submitted.

List transactions

GET /api/ledger/transactions

Returns all transactions for the authenticated user.

Response

id · string · required

Unique transaction identifier (UUID).

fromAccountId · string · required

UUID of the sender’s account.

toBeneficiaryId · string · required

UUID of the beneficiary who received the transfer.

beneficiaryName · string · required

Full name of the beneficiary at the time of the transaction.

amount · number · required

Transfer amount. Must be greater than zero.

status · string · required

Current transaction status, e.g., "completed", "pending", "failed".

speiReference · string

SPEI tracking reference number, if available.

createdAt · string · required

ISO 8601 timestamp of when the transaction was created.

curl

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

Response

[
  {
    "id": "txn-uuid",
    "fromAccountId": "account-uuid",
    "toBeneficiaryId": "ben-uuid",
    "beneficiaryName": "Juan Pérez",
    "amount": 500.00,
    "status": "completed",
    "speiReference": "SPEI20260317001",
    "createdAt": "2026-03-17T14:30:00Z"
  }
]

---

Create transaction

POST /api/ledger/transactions

Creates a new SPEI transfer from the authenticated user’s account to a saved beneficiary.

Call POST /ai/risk before this endpoint and present a confirmation dialog to the user when the risk level is medium or high. The transfer requires a beneficiary to be saved first — use POST /api/ledger/beneficiaries to add one.

Request body

fromAccountId · string · required

UUID of the account to debit.

toBeneficiaryId · string · required

UUID of the saved beneficiary to credit. The beneficiary must already exist — see Beneficiaries.

amount · number · required

Transfer amount. Must be greater than zero (0.01 minimum).

Error responses

Status	Description
400	Insufficient funds, missing fields, or invalid amount.
401	Invalid or missing bearer token.

curl

curl --request POST \
  --url http://localhost:5000/api/ledger/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "fromAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "toBeneficiaryId": "ben-uuid",
  "amount": 500.00
}'

Response (200 OK)

{
  "id": "txn-uuid",
  "fromAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "toBeneficiaryId": "ben-uuid",
  "beneficiaryName": "Juan Pérez",
  "amount": 500.00,
  "status": "completed",
  "speiReference": "SPEI20260317001",
  "createdAt": "2026-03-17T14:30:00Z"
}