Payment Orchestrator
Bank Transfer

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 Bank0124
  • Anadolubank0135
  • Burgan Bank0125
  • DenizBank0134
  • Dünya Katılım0214
  • Emlak Katılım0211
  • Enpara Bank0157
  • Fibabanka0103
  • Garanti BBVA0062
  • Halkbank0012
  • Hayat Finans Katılım0212
  • ING Bank0099
  • İstanbul Takas ve Saklama Bankası0132
  • Kuveyt Türk0205
  • Misyon Yatırım Bankası0153
  • Odeabank0146
  • QNB Finansbank0111
  • Şekerbank0059
  • TEB0032
  • Türk Ticaret Bankası0060
  • Türkiye Finans0206
  • Tü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 (422 payment.method.disabled).
  • The currency is TRY. Bank transfer does not support pre-authorization; a request with preauth: true gets 422 payment.preauth.unsupported_for_method before the payment starts.

Waiting period and late money

The Payments → Form Settings → Havale / EFT section has two settings:

SettingValueDescription
Waiting period1, 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 deadlineAccept automatically (default) / Let me decideHow 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 is bank_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

FieldTypeRequiredDescription
bankTransfer.bankCodestringYesThe 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": "…"
}
FieldTypeDescription
bankCode, bankNamestringThe bank of your account the money is sent to
holderNamestringAccount holder name; the buyer enters it as the recipient name of the transfer
ibanstringThe IBAN of your account, without spaces. You may display it in groups of four
amountMinor, currencystringThe amount to send
paymentCodestringThe payment code the buyer writes in the description (LNX + 6 characters). The code lets the transaction match this payment
expiresAtstringThe deadline (ISO 8601); the same as action.expiresAt
otherBankbooleantrue: 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:

  1. 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-p9 also matches).
  2. 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.
  3. 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.

CaseType (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 expectedUNDERPAIDThe 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 arrivedOVERPAIDThe payment completes with the expected amount; refund the excess to the buyer from your own bank and report the refund
Arrived after the period endedLATESee 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's acceptedPaymentId field and payment.captured arrives 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.

MethodPathDescription
GET/payments/bank-transfer/exceptionsExceptions. Filters: environment (TEST / LIVE), status, paymentId (only this payment's records), limit (1–200, default 50)
POST/payments/bank-transfer/exceptions/{id}/acceptAccept: LATE → a new linked payment, UNDERPAID → capture with the amount received. OVERPAID cannot be accepted
POST/payments/bank-transfer/exceptions/{id}/refundedReports 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:

EventWhen it fires
payment.bank_transfer.partially_receivedPart of the amount arrived within the period; the payment keeps waiting
payment.bank_transfer.underpaidThe period ended with less than expected; your decision is awaited
payment.bank_transfer.overpaidMore than expected arrived; the excess should be refunded
payment.bank_transfer.late_arrivalMoney 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

HTTPCodeWhen
404payment.bank_transfer.exception_not_foundThe exception was not found or does not belong to your account
409payment.bank_transfer.exception_not_pendingA decision has already been made for this record
409payment.bank_transfer.decision_not_supportedAn excess amount cannot be accepted; refund it
409payment.bank_transfer.payment_state_conflictThe payment's status does not allow this decision
409payment.bank_transfer.source_not_supportedA payment opened from a payment link cannot be re-opened; refund it
409payment.bank_transfer.amount_below_expectedThe late amount is below the expected amount; refund it
409payment.bank_transfer.order_blockedThe order has another payment
409payment.bank_transfer.order_attempt_in_flightAnother 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).

SDKPayment with the bankTransfer blockDISPLAY instructionExceptions: list, accept, report refunded
Node.jspayments.directMethodPayment · withMethodFields(PaymentMethod.BANK_TRANSFER, null, { bankCode })data.action.bankTransferlistBankTransferExceptions, acceptBankTransferException, markBankTransferExceptionRefunded
PHPpayments()->directMethodPayment · withMethodFields(PaymentMethod::BANK_TRANSFER, null, ['bankCode' => …])$result->action()->bankTransfer()listBankTransferExceptions, acceptBankTransferException, markBankTransferExceptionRefunded
.NETPayments.DirectMethodPaymentAsync · WithMethodFields(PaymentMethods.BankTransfer, null, new { bankCode })BankTransferInstruction.FromResponseListBankTransferExceptionsAsync, AcceptBankTransferExceptionAsync, MarkBankTransferExceptionRefundedAsync
GoPayments.DirectMethodPayment · WithMethodFields(lunixi.PaymentMethodBankTransfer, "", …)response.BankTransferInstruction()ListBankTransferExceptions, AcceptBankTransferException, MarkBankTransferExceptionRefunded
Javapayments().directMethodPayment · withMethodFields(PaymentMethod.BANK_TRANSFER, null, …)PaymentBankTransferInstruction.fromResponselistBankTransferExceptions, acceptBankTransferException, markBankTransferExceptionRefunded
Pythonpayments().direct_method_payment · with_method_fields(PaymentMethod.BANK_TRANSFER, None, …)BankTransferInstruction.from_responselist_bank_transfer_exceptions, accept_bank_transfer_exception, mark_bank_transfer_exception_refunded
Rubypayments.direct_method_payment · with_method_fields(Lunixi::PaymentMethod::BANK_TRANSFER, nil, bankCode: …)Lunixi::BankTransferInstruction.from_responselist_bank_transfer_exceptions, accept_bank_transfer_exception, mark_bank_transfer_exception_refunded
Rustpayments().direct_method_payment · with_method_fields(payment_method::BANK_TRANSFER, None, …)BankTransferInstruction::from_responselist_bank_transfer_exceptions, accept_bank_transfer_exception, mark_bank_transfer_exception_refunded
ElixirLunixi.Payments.direct_method_payment/3 · DirectMethodPayment.with_method_fields(…, "BANK_TRANSFER", nil, …)Lunixi.Payment.BankTransfer.instruction/1list_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.

Next steps