Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Gianluca-X/DigitalMoney/llms.txt

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

Move funds from the sender’s digital-money account to any other registered account, identified by its CVU or human-readable alias. The entire operation — balance deduction, balance credit, transference record, and dual activity entries — executes inside a single @Transactional block. Pessimistic write locking on the account rows ensures that concurrent transfers cannot produce inconsistent balances.

​
Endpoint

POST /accounts/{accountId}/transferences/money
Base URL: http://localhost:8085

​
Authentication

A valid Bearer JWT is required in the Authorization header. The path accountId must correspond to the account that owns the token; any mismatch results in 403 Forbidden.

​
Path Parameters

​
accountId
long
required
The numeric ID of the sender’s account. Funds are debited from this account.

​
Request Body

Send a JSON object mapped to TransferRequestOutDTO:
​
recipient
string
required
The CVU (22-digit string) or alias of the destination account. The service first searches by alias; if not found it falls back to CVU lookup.
​
amount
BigDecimal
required
The amount to transfer. Must be greater than 0 and must not exceed the sender’s current balance.

​
Response

Returns 201 Created with a plain-text confirmation on success. 
Transferencia realizada con éxito

​
Activity Records Created

Two Activity entries are created atomically as part of every successful transfer:
EntryaccountIdtypeamountdescription
SenderaccountId (sender)transfer-outNegative value of transferred amountRecipient CVU or alias
RecipientRecipient’s account IDtransfer-inPositive value of transferred amountSender’s CVU

​
Get Recent Recipients

Retrieve the last five accounts the sender has transferred money to: 
GET /accounts/{accountId}/transferences/last-transferred-accounts

curl -X GET "http://localhost:8085/accounts/42/transferences/last-transferred-accounts" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."
Returns an array of Transference objects ordered by date descending, limited to 5 entries. Each object includes the fields: id, accountId, cardId, amount, date, type, and recipient.

​
Business Rules

  • amount must be strictly greater than 0.
  • Self-transfers (sender and recipient resolve to the same account) are rejected with a BadRequestException.
  • The sender’s balance must be greater than or equal to amount; otherwise InsufficientFundsException is thrown.
  • Recipient lookup is performed first by alias, then by CVU. If neither resolves to a registered account, the transfer is rejected.

​
Concurrency

The makeTransferFromCash method is annotated with @Transactional. The database rows for both the sender and recipient accounts are locked for the duration of the operation, preventing race conditions when multiple concurrent transfers affect the same accounts.
Pessimistic locking is in effect. Under high concurrency, transfer requests against the same account may queue briefly while a prior transaction commits. This is by design to guarantee balance consistency.

​
Example Request

curl -X POST "http://localhost:8085/accounts/42/transferences/money" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "perro.tranquilo.rio",
    "amount": 2500.00
  }'
Using a CVU instead of an alias: 
curl -X POST "http://localhost:8085/accounts/42/transferences/money" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "0000003100098765432101",
    "amount": 2500.00
  }'

​
Example Response

Transferencia realizada con éxito

​
Error Responses

StatusExceptionCondition
400 Bad RequestAccountNotFoundExceptionThe recipient CVU/alias does not match any registered account, or a self-transfer was attempted.
403 ForbiddenUnauthorizedExceptionThe authenticated user does not have permission to debit the specified account.
410 GoneInsufficientFundsExceptionThe sender’s balance is lower than the requested transfer amount.
500 Internal Server Error—An unexpected error occurred while processing the transfer.
The controller returns 410 Gone for insufficient funds — handle this status explicitly in your client to display an appropriate low-balance warning to the user.

Build docs developers (and LLMs) love

Get started for freeTalk to us