Concepts

Bank, connection, account, balance, transaction

You set up only the connection; accounts are found under it automatically, and a balance and transactions are read for each account.

Term	Meaning	Identifier in the API
Bank	A bank in the catalog, identified by its EFT code.	`bankId`
Connection	The read connection you set up with a bank. You have one connection per bank in an environment.	`connectionId`
Account	A bank account found under a connection. Your accounts are discovered automatically once the connection is active.	`accountId`
Balance	The most recently read balance of an account.	by `accountId`
Transaction	A single line of the account statement: amount, direction, date, description.	`transactionId`
Freshness	When the data was last read and when the next read is possible.	`freshness`
Sync request	Asking for an account to be read from the bank again.	`POST …/sync`
Capability	The data types and operations available on a connection; `OUTGOING_TRANSFER` for transfers, `FX_EXCHANGE` for exchange.	`capabilities`
Transfer	Money sent from your connected account to an IBAN.	`transferId` (`id`)
Exchange quote	A short-lived rate and amount the bank gives for two of your accounts at the same bank.	`quoteId` (`id`)
Exchange order	Executing a quote.	`orderId` (`id`)
Environment	Test or live; it is the environment of your API key.	—

Connection statuses

Before data is read from the bank, a connection goes through application and setup steps. The status is in the status field; the reason for the status is given as a short code in statusReasonCode (values: Connections).

New data is read only in ACTIVE and DEGRADED. DEGRADED is not a failure: reads are retried and the connection returns to ACTIVE on its own. DISCONNECTED does not reopen; connecting again creates a new connectionId.

Status	Is new data read from the bank?	What to do
`PENDING_DOCUMENTS`	No	Deliver the application documents as the delivery instructions in the panel say.
`UNDER_REVIEW`	No	Your documents are under review; wait. If a document is rejected, the connection returns to `PENDING_DOCUMENTS`.
`PENDING_SETUP`	No	Lunixi is completing the setup; wait.
`ACTIVE`	Yes	Nothing to do; your accounts are read regularly.
`DEGRADED`	Reads are attempted but recent reads failed	The last read data is returned and may be out of date. Reads are retried automatically; watch `lastSuccessfulSyncAt`.
`SUSPENDED`	No	The connection is suspended. Check the connection details in the panel; contact Lunixi if needed.
`DISCONNECTED`	No	The connection is closed and does not reopen. To read the bank again, connect it again in the panel; the new connection gets a new `connectionId`.

When a connection is disconnected its accounts are not deleted; their status becomes INACTIVE. An account the bank no longer returns also becomes INACTIVE.

Accounts, balances and transactions that were already read stay readable through the API even when the connection is not ACTIVE. The status only determines whether new data is read from the bank.

Transaction direction and type

Every transaction has a direction (direction):

`direction`	Meaning
`CREDIT`	Money into the account
`DEBIT`	Money out of the account

amountMinor is always zero or positive; it carries no sign. Read whether money came in or went out from direction.

Banks classify transactions with their own codes. Lunixi maps those codes to a bank-independent common type (canonicalType), so you can filter the transactions of all your banks with the same types. A transaction that cannot be mapped becomes OTHER.

`canonicalType`	Meaning
`TRANSFER_IN`	Incoming transfer
`TRANSFER_OUT`	Outgoing transfer
`INTERNAL_IN`	Internal transfer in
`INTERNAL_OUT`	Internal transfer out
`POS_SETTLEMENT`	POS settlement
`POS_SETTLEMENT_REFUND`	POS refund
`FEE`	Fee / commission
`TAX`	Tax
`CASH_IN`	Cash deposit
`CASH_OUT`	Cash withdrawal
`CARD`	Card transaction
`LOAN`	Loan
`FX`	Foreign exchange
`INTEREST`	Interest
`OTHER`	Other

Money transfers

If your connection supports transfers (OUTGOING_TRANSFER in capabilities), you can send money from your connected account to an IBAN: through the API with the Money Transfers endpoints, in the panel with Para gönder (Send money). Lunixi does not check the balance; it sends the transfer to the bank and updates its status from the bank's answer.

Transfer statuses

Status	Meaning	Final?
`PENDING_OTP`	Only for a transfer started in the panel: waiting for the user's e-mail verification code. A transfer created with an API key never has this status.	No
`SUBMITTED`	The transfer is approved and sent, or queued to be sent, to the bank; waiting for the bank's answer.	No
`PROCESSING`	The bank is processing the transfer.	No
`COMPLETED`	The bank completed the transfer. It can become `RETURNED` if the receiving bank sends the money back.	Almost — a return can follow
`FAILED`	The transfer did not take place; the reason is in `failureCode`.	Yes
`RETURNED`	The completed transfer was returned by the receiving bank.	Yes
`CANCELED`	The transfer was canceled: the verification code was not confirmed in time, or the user or the bank canceled it.	Yes

Panel transfers start at PENDING_OTP, API transfers at SUBMITTED. A transfer with outcomeUnknown: true waits in SUBMITTED — do not send it again. COMPLETED is final unless the receiving bank returns the money.

PROCESSING is not seen at every bank; a transfer can settle directly from SUBMITTED.
When outcomeUnknown is true, the bank's answer is not confirmed yet and the transfer waits in SUBMITTED. Do not send the transfer again; Lunixi confirms the outcome with the bank. → Money Transfers › Unconfirmed outcome
A completed transfer also appears on your account as an outgoing transaction at the next account read; the matching transaction's id is written to the transfer's bankTransactionId.

Transfer route (`rail`)

The bank decides the route of the transfer; you do not choose it.

`rail`	Meaning
`INTERNAL`	Between your own accounts at the same bank.
`INTRABANK`	To another account at the same bank.
`FAST`	To another bank over FAST.
`EFT`	To another bank over EFT. A transfer sent after the EFT cut-off time can be rejected (`bank_connect.transfer.eft_cutoff_passed`).
`UNKNOWN`	The bank has not reported the route yet.

The field can be null until the bank reports the route.

Currency exchange

If your connection supports currency exchange (FX_EXCHANGE in capabilities), you can buy and sell currency between two of your accounts at the same bank: through the API with the Currency Exchange endpoints, in the panel with Döviz çevir (Exchange currency).

The quote blocks nothing and is short-lived; open the order before its expiresAt. Read the outcome from the order endpoint — no webhook is sent for exchange orders.

Concept	Description
Source account	The account of the currency you sell; the amount leaves it.
Target account	The account of the currency you buy; the amount enters it. Same connection as the source account, different currency.
Quote	The rate the bank will apply and the amount on both sides. It blocks nothing; the bank sets its validity (usually a minute or two). A quote serves one order.
Order	Executing the quote. It opens `SUBMITTED` and becomes `COMPLETED` or `FAILED` from the bank's answer.

No webhook is sent for exchange orders; read the outcome from the order endpoint.

Freshness

Your accounts are read from the bank at intervals; the data is not real time. Each account reports how fresh its data is in the freshness object:

Field	Meaning
`lastSuccessfulSyncAt`	Time of the last successful read from the bank
`nextSyncAvailableAt`	Earliest time of the next read
`minSyncIntervalSeconds`	Shortest time between two reads (seconds). The value may differ per connection; do not assume a fixed value, read it from this field.

The read interval cannot be shortened. A sync request respects this interval too: if the interval has not elapsed, the read is scheduled for nextSyncAvailableAt.

While a connection is DEGRADED, reads fail, so the data may get stale; lastSuccessfulSyncAt does not advance.

Environment

Your API key determines the environment. A test key (mk_test_…) sees only connections and data in the test environment, a live key (mk_live_…) only those in the live environment. You do not send an environment in the request; if you do, the request is rejected with 400 VALIDATION_ERROR. For the test environment see Test Environment.

Masking

Personal and sensitive bank data is returned masked in the API and in webhooks:

Data	Field	Format
Your account's IBAN	`ibanMasked`	`TR00 ** 00 00` — country code, check digits and last 4 digits visible
Account number	`accountNumberMasked`	`****0000` — last 4 digits visible
Counterparty name	`counterpartyNameMasked`	`Ö** A**` — first letter of each word visible
Counterparty IBAN	`counterpartyIbanMasked`	Same format as the IBAN
Transfer receiver's IBAN and name	`receiverIbanMasked`, `receiverNameMasked`	Same format as the IBAN and the name

Never returned: the full IBAN, the full account number, the account holder's name, the full name of the counterparty or of the transfer receiver, and tax or national ID numbers.

⚠️

The transaction description (description) is returned as the bank wrote it, unmasked, so you can match it against reference codes in payment descriptions. Information the bank put in the description (for example the sender's name) may appear in this field as is.

Overview Connect a Bank in the Panel