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.

Loading the search index…

Transfers between accounts

Objects

MoneyTransfer

  • idintegerrequired

    ID of the transfer — the transfer_id of its legs in the money journal (/v1/money-transactions).

  • versionintegerrequired

    Version of the record: it grows with every change. Send it as the ETag in If-Match to change the record.

  • from_account_idintegerrequired

    ID of the money account the money left.

  • to_account_idintegerrequired

    ID of the money account the money arrived at.

  • from_amountstringrequired

    Amount taken from from_account_id in its currency, as a decimal string.

  • from_currencystringrequired

    Currency of the source account: ISO 4217 code or crypto code.

  • to_amountstringrequired

    Amount 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_currencystringrequired

    Currency of the destination account.

  • feestring or nullrequired

    Transfer 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.

  • amountintegerrequired

    Value 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.

  • currencystringrequired

    Currency of the amounts, an ISO 4217 code: the currency of the store.

  • occurred_atstring (date-time)required

    Moment of the transfer.

  • occurred_onstring (date)required

    Accounting date of the transfer, YYYY-MM-DD in the store time zone.

  • descriptionstring or nullrequired

    Description of the transfer; null when not set.

  • from_transaction_idintegerrequired

    ID of the expense transaction on the source account.

  • to_transaction_idintegerrequired

    ID of the income transaction on the destination account.

  • fee_transaction_idinteger or nullrequired

    ID of the fee transaction; null when there is no fee.

  • created_atstring (date-time)required

    When the record was created.

Endpoints

Get a transfer between money accounts

get/money-transfers/{money_transfer}

Scope: finance:read

Parameters

Path

  • money_transferintegerrequired

    ID of the transfer — the transfer_id of its legs in the money journal.

Responses

200Success

Headers

  • ETagstringrequired

    Version 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl "https://api.saleya.app/v1/money-transfers/{money_transfer}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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_transferintegerrequired

    ID of the transfer — the transfer_id of its legs in the money journal.

Header

  • Idempotency-Keystring

    Unique 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-Matchstringrequired

    ETag 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_idinteger

    ID of the money account the money left.

    Minimum:
    1
  • to_account_idinteger

    ID of the money account the money arrived at.

    Minimum:
    1
  • from_amountstring

    Amount taken from from_account_id in its currency, as a decimal string.

    Max length:
    37
  • to_amountstring or null

    Amount 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 null

    Transfer 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 null

    Description of the transfer; null when not set.

    Max length:
    1000

Responses

200Success

Headers

  • Idempotent-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns Problem

Errors of this endpoint

Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors

Example request
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
Request body — 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"
}
Example response · 200
{
  "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_transferintegerrequired

    ID of the transfer — the transfer_id of its legs in the money journal.

Header

  • Idempotency-Keystring

    Unique 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-Matchstringrequired

    ETag 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-Replayedstring

    true 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns Problem

Errors of this endpoint

Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors

Example request
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-Keystring

    Unique 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_idintegerrequired

    ID of the money account the money left.

    Minimum:
    1
  • to_account_idintegerrequired

    ID of the money account the money arrived at.

    Minimum:
    1
  • from_amountstringrequired

    Amount taken from from_account_id in its currency, as a decimal string.

    Max length:
    37
  • to_amountstring or null

    Amount 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 null

    Transfer 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 null

    Description of the transfer; null when not set.

    Max length:
    1000

Responses

201Created

Headers

  • Idempotent-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version of the record. Send it in If-Match to change the record.

    Example:
    "7"
  • Locationstring (uri)required

    Address 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns Problem

Errors of this endpoint

Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors

Example request
curl -X POST "https://api.saleya.app/v1/money-transfers" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — 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"
}
Example response · 201
{
  "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"
}