Transfers between accounts
Money transfer from one account to another with a fee: create, update and delete. Transfer legs are money transactions with transfer_id.
Transfers between accounts
Objects
MoneyTransfer
idintegerrequiredID of the transfer — the transfer_id of its legs in the money journal (/v1/money-transactions).
versionintegerrequiredVersion of the record: it grows with every change. Send it as the ETag in If-Match to change the record.
from_account_idintegerrequiredID of the money account the money left.
to_account_idintegerrequiredID of the money account the money arrived at.
from_amountstringrequiredAmount taken from from_account_id in its currency, as a decimal string.
from_currencystringrequiredCurrency of the source account: ISO 4217 code or crypto code.
to_amountstringrequiredAmount credited to to_account_id in its currency, as a decimal string. In the same currency it equals from_amount: any difference is the fee.
to_currencystringrequiredCurrency of the destination account.
feestring or nullrequiredTransfer fee in the currency of the source account, as a decimal string — an expense on the system category bank_fees; null when there is no fee.
amountintegerrequiredValue of the transfer in minor units of the store currency: both legs carry it. The ledger posts the exchange difference of a currency exchange as a separate transaction.
currencystringrequiredCurrency of the amounts, an ISO 4217 code: the currency of the store.
occurred_atstring (date-time)requiredMoment of the transfer.
occurred_onstring (date)requiredAccounting date of the transfer, YYYY-MM-DD in the store time zone.
descriptionstring or nullrequiredDescription of the transfer; null when not set.
from_transaction_idintegerrequiredID of the expense transaction on the source account.
to_transaction_idintegerrequiredID of the income transaction on the destination account.
fee_transaction_idinteger or nullrequiredID of the fee transaction; null when there is no fee.
created_atstring (date-time)requiredWhen the record was created.
Endpoints
Get a transfer between money accounts
get/money-transfers/{money_transfer}
Scope: finance:read
Parameters
Path
money_transferintegerrequiredID of the transfer — the transfer_id of its legs in the money journal.
Responses
200Success
Headers
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns MoneyTransfer
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/money-transfers/{money_transfer}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"version": 0,
"from_account_id": 0,
"to_account_id": 0,
"from_amount": "string",
"from_currency": "string",
"to_amount": "string",
"to_currency": "string",
"fee": "string",
"amount": 0,
"currency": "string",
"occurred_at": "2026-01-15T12:00:00Z",
"occurred_on": "2026-01-15",
"description": "string",
"from_transaction_id": 0,
"to_transaction_id": 0,
"fee_transaction_id": 0,
"created_at": "2026-01-15T12:00:00Z"
}Update a whole transfer in place: accounts, amounts, fee, date and description
patch/money-transfers/{money_transfer}
Scope: finance:write
Parameters
Path
money_transferintegerrequiredID of the transfer — the transfer_id of its legs in the money journal.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringrequiredETag of the record from the last read, for example "7". The change applies only if nobody changed the record since then; otherwise 412. Without it — 428.
- Example:
"7"
Request body application/json
from_account_idintegerID of the money account the money left.
- Minimum:
- 1
to_account_idintegerID of the money account the money arrived at.
- Minimum:
- 1
from_amountstringAmount taken from from_account_id in its currency, as a decimal string.
- Max length:
- 37
to_amountstring or nullAmount credited to to_account_id in its currency, as a decimal string. In the same currency it equals from_amount: any difference is the fee.
- Max length:
- 37
feestring or nullTransfer fee in the currency of the source account, as a decimal string — an expense on the system category bank_fees; null when there is no fee.
- Max length:
- 37
occurred_onstring (date)Accounting date of the transfer, YYYY-MM-DD in the store time zone.
occurred_atstring (date-time)Moment of the transfer.
descriptionstring or nullDescription of the transfer; null when not set.
- Max length:
- 1000
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns MoneyTransfer
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
412The record changed after it was read: the version in If-Match is not current
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
428The request needs If-Match with the ETag of the record
application/problem+json
Returns Problem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X PATCH "https://api.saleya.app/v1/money-transfers/{money_transfer}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"from_account_id": 1,
"to_account_id": 1,
"from_amount": "string",
"to_amount": "string",
"fee": "string",
"occurred_on": "2026-01-15",
"occurred_at": "2026-01-15T12:00:00Z",
"description": "string"
}{
"id": 0,
"version": 0,
"from_account_id": 0,
"to_account_id": 0,
"from_amount": "string",
"from_currency": "string",
"to_amount": "string",
"to_currency": "string",
"fee": "string",
"amount": 0,
"currency": "string",
"occurred_at": "2026-01-15T12:00:00Z",
"occurred_on": "2026-01-15",
"description": "string",
"from_transaction_id": 0,
"to_transaction_id": 0,
"fee_transaction_id": 0,
"created_at": "2026-01-15T12:00:00Z"
}Delete a transfer with all its legs
delete/money-transfers/{money_transfer}
Scope: finance:write
Parameters
Path
money_transferintegerrequiredID of the transfer — the transfer_id of its legs in the money journal.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringrequiredETag of the record from the last read, for example "7". The change applies only if nobody changed the record since then; otherwise 412. Without it — 428.
- Example:
"7"
Responses
204Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
No body
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
412The record changed after it was read: the version in If-Match is not current
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
428The request needs If-Match with the ETag of the record
application/problem+json
Returns Problem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 409
in_use_conflictRecord in use - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X DELETE "https://api.saleya.app/v1/money-transfers/{money_transfer}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"'Transfer money between accounts, with or without a fee
post/money-transfers
Scope: finance:write
Parameters
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Request body application/json
from_account_idintegerrequiredID of the money account the money left.
- Minimum:
- 1
to_account_idintegerrequiredID of the money account the money arrived at.
- Minimum:
- 1
from_amountstringrequiredAmount taken from from_account_id in its currency, as a decimal string.
- Max length:
- 37
to_amountstring or nullAmount credited to to_account_id in its currency, as a decimal string. In the same currency it equals from_amount: any difference is the fee.
- Max length:
- 37
feestring or nullTransfer fee in the currency of the source account, as a decimal string — an expense on the system category bank_fees; null when there is no fee.
- Max length:
- 37
occurred_onstring (date)Accounting date of the transfer, YYYY-MM-DD in the store time zone.
occurred_atstring (date-time)Moment of the transfer.
descriptionstring or nullDescription of the transfer; null when not set.
- Max length:
- 1000
Responses
201Created
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
Locationstring (uri)requiredAddress of the created record; for an accepted request (202), the address to follow its outcome.
application/json
Returns MoneyTransfer
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/money-transfers" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"from_account_id": 1,
"to_account_id": 1,
"from_amount": "string",
"to_amount": "string",
"fee": "string",
"occurred_on": "2026-01-15",
"occurred_at": "2026-01-15T12:00:00Z",
"description": "string"
}{
"id": 0,
"version": 0,
"from_account_id": 0,
"to_account_id": 0,
"from_amount": "string",
"from_currency": "string",
"to_amount": "string",
"to_currency": "string",
"fee": "string",
"amount": 0,
"currency": "string",
"occurred_at": "2026-01-15T12:00:00Z",
"occurred_on": "2026-01-15",
"description": "string",
"from_transaction_id": 0,
"to_transaction_id": 0,
"fee_transaction_id": 0,
"created_at": "2026-01-15T12:00:00Z"
}