Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Alejandrin08/Hackathon-SPEI/llms.txt

Use this file to discover all available pages before exploring further.

The ledger system manages bank accounts, beneficiaries, and SPEI transfers. All operations require JWT authentication. The BaseController extracts the authenticated user’s ID from the ClaimTypes.NameIdentifier JWT claim on every request.
SPEI (Sistema de Pagos Electrónicos Interbancarios) is Mexico’s interbank electronic payment network. Transfers settle in seconds between any CLABE-enabled account.

​
Accounts

Each user can hold one or more bank accounts. Accounts are identified by their accountNumber field, which can be a CLABE (Clave Bancaria Estandarizada) for incoming SPEI transfers.

Create account

POST /api/ledger/accountsCreates a new bank account for the authenticated user using a provided account number and type.

List accounts

GET /api/ledger/accountsReturns all accounts belonging to the authenticated user, including current balances.
Example account object: 
{
  "id": "acc_001",
  "accountNumber": "646180157000000001",
  "accountType": "DEFAULT",
  "balance": 12500.00,
  "currency": "MXN"
}

​
Beneficiaries

Beneficiaries are trusted recipients saved by the user. Adding a beneficiary before sending money simplifies recurring transfers and enables the risk model to detect first-time recipients.

Add beneficiary

POST /api/ledger/beneficiariesSaves a new recipient with their name, account number, and bank name.

List beneficiaries

GET /api/ledger/beneficiariesReturns all saved beneficiaries for the authenticated user.

Remove beneficiary

DELETE /api/ledger/beneficiaries/{id}Removes a beneficiary from the user’s saved list.
Example beneficiary object: 
{
  "id": "ben_042",
  "name": "María López",
  "alias": "María",
  "accountNumber": "646180157000000099",
  "bankName": "BBVA",
  "isFavorite": false
}

​
Transactions

Create transaction

POST /api/ledger/transactionsInitiates a SPEI transfer. Called only after the user has confirmed via ConfirmDialog.

List transactions

GET /api/ledger/transactionsReturns the transaction history for the authenticated user, ordered by timestamp descending.
Example transaction object: 
{
  "id": "txn_789",
  "fromAccountId": "acc_001",
  "toBeneficiaryId": "ben_042",
  "beneficiaryName": "María López",
  "amount": 3000.00,
  "status": "completed",
  "speiReference": "SPEI20260317001",
  "createdAt": "2026-03-17T14:32:00Z"
}

​
Transfer flow

1

Navigate to Transfer

The user opens TransferView (the Send Money screen).
2

Select or add a beneficiary

The user picks a recipient from their saved beneficiary list, or adds a new beneficiary by entering a name, account number, and bank name.
3

Enter amount

The user types the transfer amount. Basic validation (positive number, sufficient balance) runs client-side.
4

Risk evaluation

Before showing the confirmation screen, the frontend calls POST /ai/risk with the transaction details.
{
  "amount": 3000.00,
  "is_new_beneficiary": false,
  "hour_of_day": 14,
  "num_past_transactions": 12,
  "avg_transaction_amount": 2800.00,
  "max_transaction_amount": 6000.00,
  "num_transactions_to_beneficiary": 5,
  "is_new_device": false,
  "geolocation_changed": false
}
See the risk detection documentation for full response details.
5

Review risk alert (if applicable)

If the risk level is medium or high, the RiskBadge component shows the risk level and ConfirmDialog presents a plain-language explanation of the detected risk factors. The user can review or cancel before continuing.
6

Confirm the transaction

The user taps Confirm in ConfirmDialog. The frontend calls:
POST /api/ledger/transactions

{
  "fromAccountId": "acc_001",
  "toBeneficiaryId": "ben_042",
  "amount": 3000.00
}
7

Success notification

On a successful response, a toast notification confirms the transfer. The user is returned to the home screen and the account balance updates immediately.

​
Frontend views

ViewDescription
TransferViewSend money to a saved beneficiary or a new recipient
ReceiveViewDisplay the user’s CLABE number so others can send money to them
PayServicesViewPay bills and services using the same SPEI transfer mechanism

Build docs developers (and LLMs) love

Get started for freeTalk to us