Bank Transfer
With paymentMethod: "BANK_TRANSFER" the buyer sends the amount from their own bank by bank transfer (havale), EFT or FAST. The money arrives directly in your bank account; Lunixi does not hold the money and does not debit your account. Lunixi shows the buyer the payment instruction, reads the incoming transaction from your account through Bank Accounts and matches it to the payment.
All amounts are canonical minor-unit strings: "amount": "125000" = ₺1,250.00. The request, response and error rules shared by all methods are on the Payment page.
How it works
Connect your bank account (once)
Connect the bank accounts you will collect into in the Bank Accounts product. The banks of your active TRY accounts become the banks the buyer can choose. See Prerequisites.
The buyer picks their bank and sees the instruction
The buyer chooses the bank they will pay from. The instruction shows the IBAN of your account at that bank, the account holder name, the amount, a payment code and the deadline. If the buyer's bank is not listed, they send an EFT/FAST through the Other banks option.
The buyer sends the money
The buyer sends the amount in the instruction and writes the payment code in the description. Meanwhile the payment waits (PROCESSING); you set the waiting period (1–3 business days).
The transaction matches and the payment completes
When the transaction in your account matches the payment, the payment becomes CAPTURED and the payment.captured webhook arrives. If the period ends and no money arrives, the payment becomes FAILED. For late, short or excess money see Exceptions.
Lunixi Bank Transfer and banks
Lunixi's own provider, Lunixi Havale/EFT, runs the method: no key or password, the money arrives in your own account, the transaction is matched automatically by the payment code, and partial, short, excess and late money as well as manual matching are supported. Setup and features: Bank Transfer Providers.
The buyer sees the banks among these where you connected an account (transfer); if their bank is not listed they send an EFT/FAST through Other banks.
Akbank0046
Aktif Bank0143
Albaraka Türk0203
Alternatif Bank0124Anadolubank0135
Burgan Bank0125
DenizBank0134
Dünya Katılım0214
Emlak Katılım0211
Enpara Bank0157
Fibabanka0103Garanti BBVA0062
Halkbank0012
Hayat Finans Katılım0212
ING Bank0099
İstanbul Takas ve Saklama Bankası0132Kuveyt Türk0205
Misyon Yatırım Bankası0153
Odeabank0146
QNB Finansbank0111Şekerbank0059
TEB0032
Türk Ticaret Bankası0060
Türkiye Finans0206Türkiye İş Bankası0064
Vakıf Katılım0210
VakıfBank0015
Yapı Kredi0067
Ziraat Bankası0010
Ziraat Katılım0209
Prerequisites
Bank Accounts and collection accounts
- The Bank Accounts product must be enabled on your account and at least one bank you will collect into must be connected. Only the banks of your active TRY accounts are shown to the buyer.
- If you have more than one account at the same bank, choose which one appears in the instruction under POS Center → Lunixi Havale/EFT → Collection accounts in the panel. Without a choice, the first connected account at that bank is shown.
- The Other banks option is shown once you choose an account for "Other banks" in the same section. Without it, the buyer can only choose one of the banks where you have an account.
- You can change the order of the banks on the form and whether each is shown in the Bank Transfer row of Payments → Form Settings → Payment options. Without a setting, every bank is shown.
Enabling the method
- Enable the method per environment (Live / Test) with Enable on the POS Center → Lunixi Havale/EFT screen in the panel. No key or password is entered for this method.
- Enable the Bank Transfer method on the Payments → Form Settings screen. A method disabled in the panel is disabled on every channel: it is not shown on the form, it is not in the method list and it cannot be started with the Direct API (
422payment.method.disabled). - The currency is
TRY. Bank transfer does not support pre-authorization; a request withpreauth: truegets422payment.preauth.unsupported_for_methodbefore the payment starts.
Waiting period and late money
The Payments → Form Settings → Havale / EFT section has two settings:
| Setting | Value | Description |
|---|---|---|
| Waiting period | 1, 2 or 3 business days (default 1) | The time the buyer has to send the money. The period is counted in business days after the day the payment opens and ends at the end of the last business day (23:59:59 Istanbul time); weekends are not counted. For example, a 1-business-day payment opened on Friday ends at the end of Monday |
| Money arriving after the deadline | Accept automatically (default) / Let me decide | How a transfer with the payment code that arrives within 7 days after the deadline is handled. See Late money |
Method row
When the method is enabled and you have at least one collection account, the GET /payments/methods response contains a BANK_TRANSFER row. The banks the buyer can choose are the options of the bankCode field in inputFields; the value is the 4-digit BKM bank code. The Other banks option has the code 9999 and is last in the list.
{
"paymentMethod": "BANK_TRANSFER",
"category": "TRANSFER",
"blockName": "bankTransfer",
"providers": [
{
"actionTypes": ["DISPLAY"],
"inputFields": [
{
"key": "bankCode",
"type": "SELECT",
"required": true,
"label": "Bank you will pay from",
"options": [
{ "value": "0062", "label": "Garanti BBVA" },
{ "value": "0010", "label": "Ziraat Bankası" },
{ "value": "9999", "label": "Other banks" }
]
}
]
}
]
}The options are built from your collection accounts; the list changes by itself when you add or remove an account. Do not hard-code bank codes in your application; read them from this response.
With the Checkout Form
On the form, the Checkout Form SDK makes the bank transfer calls. The code you write is the same as for card payments: create an intent on your server and mount the form on your page → Checkout Form.
- If you send
"paymentMethod": "BANK_TRANSFER"in the intent, the form opens directly with Bank Transfer. Otherwise the buyer chooses the method among the other enabled methods on the form; the group of Bank Transfer isbank_transfer. - The buyer chooses their bank and sees the instruction screen: the bank's logo, the account holder, the IBAN, the amount and the payment code (the IBAN, amount and code are copied with one tap), the deadline and the time left.
- The form reads the payment status at regular intervals. For a partial transfer the instruction screen shows the amount received and the amount remaining. When the payment completes, the buyer is redirected to your
callbackUrl. - The buyer can close the page: the payment stays open until the deadline and completes when the money arrives. Always track the outcome with webhooks.
- If the buyer changes their mind before sending money, they can choose another method with Pay with another method on the instruction screen. The instruction is cancelled, this payment becomes
FAILED(payment.failed) and the form opens a new payment for the same order; the outcome arrives with the new payment's ID. If any money has arrived, even partially, the instruction is not cancelled. Money that arrives with the old payment code after the cancellation is recorded as late money.
With the Direct API
Start the payment from your server with POST /payments/direct/payment. A Bearer token, the request signature and Idempotency-Key are required → Payment — Request.
Method fields
| Field | Type | Required | Description |
|---|---|---|---|
bankTransfer.bankCode | string | Yes | The bank the buyer will pay from: one of the bankCode options in the method row. "9999" for banks that are not listed |
Example request
{
"paymentMethod": "BANK_TRANSFER",
"amount": "125000",
"currency": "TRY",
"orderId": "ORDER-2041",
"bankTransfer": { "bankCode": "0062" }
}Response and instruction
The response returns 202; the payment is PROCESSING and action.type is DISPLAY. Show the instruction to the buyer with the action.bankTransfer fields; do not call confirm or resend.
{
"status": "partial",
"code": "CUSTOMER_ACTION_REQUIRED",
"message": "…",
"data": {
"paymentId": "a71c2e4b-0f6d-4b8a-9c1e-2d3f4a5b6c7d",
"orderId": "ORDER-2041",
"status": "PROCESSING",
"paymentMethod": "BANK_TRANSFER",
"providerCode": "<providerCode>",
"action": {
"id": "act_1f4e7a2b9c3d4e5f6a7b8c9d0e1f2a3b",
"type": "DISPLAY",
"expiresAt": "2026-11-18T20:59:59.999Z",
"bankTransfer": {
"bankCode": "0062",
"bankName": "Garanti BBVA",
"holderName": "ÖRNEK TİCARET A.Ş.",
"iban": "TR000006200000000000000001",
"amountMinor": "125000",
"currency": "TRY",
"paymentCode": "LNXK7Q3P9",
"expiresAt": "2026-11-18T20:59:59.999Z",
"otherBank": false
}
}
},
"statusCode": 202,
"requestId": "…"
}| Field | Type | Description |
|---|---|---|
bankCode, bankName | string | The bank of your account the money is sent to |
holderName | string | Account holder name; the buyer enters it as the recipient name of the transfer |
iban | string | The IBAN of your account, without spaces. You may display it in groups of four |
amountMinor, currency | string | The amount to send |
paymentCode | string | The payment code the buyer writes in the description (LNX + 6 characters). The code lets the transaction match this payment |
expiresAt | string | The deadline (ISO 8601); the same as action.expiresAt |
otherBank | boolean | true: the buyer chose "Other banks"; the instruction is for EFT/FAST |
When you show the instruction, tell the buyer clearly that the payment code must be written in the description. Without the code, matching is tried by the exact amount; see Matching.
Matching
Every transfer arriving in your account is linked to a payment in this order:
- Payment code: if the description contains the payment code, the transaction is linked to that payment. Case, spaces and hyphens do not matter (
lnx k7q3-p9also matches). - Exact amount: without a code, the transaction is linked to a payment on the same account if there is exactly one payment within its period whose remaining amount equals the amount received.
- Manual matching: a transaction that fits more than one payment, or has no code and an amount that does not fit, is not linked automatically; you link it in the panel under Bank Connections → Transactions → Unmatched transfers. This tab lists transactions received in the last 8 days and the payments each can be linked to.
The sender's IBAN is not used for matching. Transactions are read from your bank at regular intervals; matching is not instant and usually happens within minutes.
Exceptions
Money that differs from what was expected is kept as an exception record and reported by webhook. When your decision is needed you also get a notification in the panel bell; it opens the payment detail. In the panel the records sit in the Bank transfer records card on the payment detail, and you decide there. You can see every payment awaiting your decision under Payments → Transactions with the Awaiting your decision filter. In the API the records are listed on the exception endpoints.
| Case | Type (kind) | What happens |
|---|---|---|
| Partial transfer within the period | — | The parts are added up; the payment keeps waiting. payment.bank_transfer.partially_received arrives for each part |
| The period ended with less than expected | UNDERPAID | The payment waits for your decision. If you accept, the payment becomes CAPTURED with the amount received; if you report a refund, the payment becomes FAILED |
| More than expected arrived | OVERPAID | The payment completes with the expected amount; refund the excess to the buyer from your own bank and report the refund |
| Arrived after the period ended | LATE | See Late money |
Late money
A payment whose period ends becomes FAILED. A transfer with the payment code that arrives within 7 days after the deadline is recorded as LATE:
- With Accept automatically, a new linked payment is opened for the same order and becomes
CAPTURED; the new payment's ID is in the exception'sacceptedPaymentIdfield andpayment.capturedarrives for that payment. - With Let me decide, the record waits for your decision: if you accept, a new linked payment is opened; otherwise you refund the money and report it.
- No new payment is opened if the order has another successful or ongoing payment, if the payment was opened from a payment link, or if the late amount is below the expected amount; refund the money.
A refund is made by sending the money back to the buyer from your own bank; Lunixi does not send money. Reporting "I refunded" closes the record; it does not make the refund itself.
Exception endpoints
The endpoints require a Bearer token and the request signature. The decision endpoints require the payment:refund permission on your API key.
| Method | Path | Description |
|---|---|---|
GET | /payments/bank-transfer/exceptions | Exceptions. Filters: environment (TEST / LIVE), status, paymentId (only this payment's records), limit (1–200, default 50) |
POST | /payments/bank-transfer/exceptions/{id}/accept | Accept: LATE → a new linked payment, UNDERPAID → capture with the amount received. OVERPAID cannot be accepted |
POST | /payments/bank-transfer/exceptions/{id}/refunded | Reports that you refunded the money; the record becomes REFUNDED |
{
"items": [
{
"id": "3d2b…",
"paymentId": "a71c…",
"kind": "UNDERPAID",
"status": "PENDING_DECISION",
"environment": "LIVE",
"amountMinor": "100000",
"currency": "TRY",
"expectedMinor": "125000",
"receivedMinor": "100000",
"counterpartyNameMasked": "A*** Y***",
"acceptedPaymentId": null,
"refundSource": null,
"decidedAt": null,
"refundedAt": null,
"createdAt": "2026-11-19T07:12:44.000Z"
}
]
}Statuses (status): PENDING_DECISION (awaiting decision), ACCEPTED, REFUND_PENDING (refund expected), REFUNDED. The sender name is returned masked only.
Webhooks
The payment's outcome arrives with the common payment events: payment.captured, payment.failed. Fulfil the order only on payment.captured. While the payment waits you can also read its status with GET /payments/:id; while it waits, action.bankTransfer in the response carries the instruction and, for partial transfers, the received (receivedMinor) and remaining (remainingMinor) amounts. In addition:
| Event | When it fires |
|---|---|
payment.bank_transfer.partially_received | Part of the amount arrived within the period; the payment keeps waiting |
payment.bank_transfer.underpaid | The period ended with less than expected; your decision is awaited |
payment.bank_transfer.overpaid | More than expected arrived; the excess should be refunded |
payment.bank_transfer.late_arrival | Money arrived after the period ended |
Besides the payment's fields, these events carry data.bankTransfer: expectedMinor, receivedMinor, remainingMinor, excessMinor, currency, late and the parts received (transfers[]: amountMinor, bookedAt, counterpartyNameMasked). Events that open an exception also carry exceptionId, kind and amountMinor. Each event is sent once per payment and transaction.
Refunds
For a payment taken by bank transfer the money is in your account; you refund the buyer from your own bank.
For an exception record (late, short or excess money) you do not need to report the refund: when you send at least the record's amount from one of your Bank Connections accounts back to the IBAN that sent the money, Lunixi sees the outgoing transaction and marks the record REFUNDED by itself (refundSource: BANK_VERIFIED). This needs your bank to include the counterparty IBAN in its transactions. If you refunded from another account or the record did not close, report it (refundSource: MERCHANT_DECLARED).
Errors
| HTTP | Code | When |
|---|---|---|
404 | payment.bank_transfer.exception_not_found | The exception was not found or does not belong to your account |
409 | payment.bank_transfer.exception_not_pending | A decision has already been made for this record |
409 | payment.bank_transfer.decision_not_supported | An excess amount cannot be accepted; refund it |
409 | payment.bank_transfer.payment_state_conflict | The payment's status does not allow this decision |
409 | payment.bank_transfer.source_not_supported | A payment opened from a payment link cannot be re-opened; refund it |
409 | payment.bank_transfer.amount_below_expected | The late amount is below the expected amount; refund it |
409 | payment.bank_transfer.order_blocked | The order has another payment |
409 | payment.bank_transfer.order_attempt_in_flight | Another payment for the order is in progress |
Common errors when starting a payment are on the Payment — Errors page.
With the SDKs
All nine server SDKs handle bank transfer the same way: start the payment with the method block, read the DISPLAY instruction, then list and decide exceptions. The block takes no provider code; the SDK refuses one before sending. Each SDK has a constant for the Other banks code (9999).
| SDK | Payment with the bankTransfer block | DISPLAY instruction | Exceptions: list, accept, report refunded |
|---|---|---|---|
| Node.js | payments.directMethodPayment · withMethodFields(PaymentMethod.BANK_TRANSFER, null, { bankCode }) | data.action.bankTransfer | listBankTransferExceptions, acceptBankTransferException, markBankTransferExceptionRefunded |
| PHP | payments()->directMethodPayment · withMethodFields(PaymentMethod::BANK_TRANSFER, null, ['bankCode' => …]) | $result->action()->bankTransfer() | listBankTransferExceptions, acceptBankTransferException, markBankTransferExceptionRefunded |
| .NET | Payments.DirectMethodPaymentAsync · WithMethodFields(PaymentMethods.BankTransfer, null, new { bankCode }) | BankTransferInstruction.FromResponse | ListBankTransferExceptionsAsync, AcceptBankTransferExceptionAsync, MarkBankTransferExceptionRefundedAsync |
| Go | Payments.DirectMethodPayment · WithMethodFields(lunixi.PaymentMethodBankTransfer, "", …) | response.BankTransferInstruction() | ListBankTransferExceptions, AcceptBankTransferException, MarkBankTransferExceptionRefunded |
| Java | payments().directMethodPayment · withMethodFields(PaymentMethod.BANK_TRANSFER, null, …) | PaymentBankTransferInstruction.fromResponse | listBankTransferExceptions, acceptBankTransferException, markBankTransferExceptionRefunded |
| Python | payments().direct_method_payment · with_method_fields(PaymentMethod.BANK_TRANSFER, None, …) | BankTransferInstruction.from_response | list_bank_transfer_exceptions, accept_bank_transfer_exception, mark_bank_transfer_exception_refunded |
| Ruby | payments.direct_method_payment · with_method_fields(Lunixi::PaymentMethod::BANK_TRANSFER, nil, bankCode: …) | Lunixi::BankTransferInstruction.from_response | list_bank_transfer_exceptions, accept_bank_transfer_exception, mark_bank_transfer_exception_refunded |
| Rust | payments().direct_method_payment · with_method_fields(payment_method::BANK_TRANSFER, None, …) | BankTransferInstruction::from_response | list_bank_transfer_exceptions, accept_bank_transfer_exception, mark_bank_transfer_exception_refunded |
| Elixir | Lunixi.Payments.direct_method_payment/3 · DirectMethodPayment.with_method_fields(…, "BANK_TRANSFER", nil, …) | Lunixi.Payment.BankTransfer.instruction/1 | list_bank_transfer_exceptions/2, accept_bank_transfer_exception/2, mark_bank_transfer_exception_refunded/2 |
The instruction reader returns nothing when there is no DISPLAY action. Examples are in the Payment methods and bank transfer section of each SDK guide.