Payment Orchestrator
Open Banking

Open Banking — Payment

With paymentMethod: "OPEN_BANKING" the buyer pays directly from their bank account without entering card details. The buyer chooses their bank on your screen, is redirected to the bank's page, signs in there, approves the payment order and comes back to you. The money moves from the buyer's account to your provider account.

The payment runs through a REDIRECT action: you do not ask the buyer for a code and you do not call confirm. The final result is verified with the provider and reported with the payment.captured or payment.failed webhook.

All amounts are canonical minor-unit strings: "amount": "250000" = ₺2,500.00. The request, response and error rules shared by all methods are on Payment.

The buyer can also pay without choosing a bank: they enter their IBAN and approve the payment request in their banking app. This option is Request to Pay and is shown separately from the bank rows → Request to Pay.

How it works

Let the buyer choose the bank

Show the buyer the banks in the method row's banks list; the buyer chooses the bank that holds their account. See Bank selection.

Start the payment

Start the payment with the Checkout Form or from your server with the Direct API. The response (202) carries a REDIRECT action.

Redirect the buyer

Send the buyer's browser to action.redirect.url. The buyer moves to the chosen bank's page, signs in and approves the payment order. In the Checkout Form the form does this step.

Receive the result

When the buyer comes back, the platform queries the result from the provider. The browser arrives at your callbackUrl with a signed form POST; the final result is reported with the payment.captured or payment.failed webhook. Ship the order on payment.captured.

Prerequisites

  • Connect your open banking provider in the panel under POS Center → Discover; the connection details and settings are on Open Banking Providers.
  • Enable the Open Banking method in the panel under Payment → Form Settings and select the provider. A method disabled in the panel is disabled on every channel; a Direct API request gets 422 payment.method.disabled.
  • Set which banks are open in your contract in the Agreement Permissions section of your provider connection; see Bank permissions.
  • The currency is TRY. The payment is a single charge: there are no installments and no pre-authorization. With preauth: true the request gets 422 payment.preauth.unsupported_for_method before the payment starts.
  • Open Banking cannot be used as a leg of a split payment.

Method row

The OPEN_BANKING row of the GET /payments/methods response carries the banks you can show the buyer in the banks field. The same banks are also the bankCode options in the provider's inputFields definition. The output below is abridged:

{
  "paymentMethod": "OPEN_BANKING",
  "category": "TRANSFER",
  "blockName": "openBanking",
  "displayName": null,
  "providerSelection": "OPTIONAL",
  "providerSelectionMode": "BUYER",
  "actionTypes": ["REDIRECT"],
  "currencies": ["TRY"],
  "preauth": false,
  "providers": [
    {
      "providerCode": "COMPAY",
      "displayName": "Compay",
      "logoUrl": null,
      "actionTypes": ["REDIRECT"],
      "currencies": ["TRY"],
      "preauth": false,
      "inputFields": [
        {
          "key": "bankCode",
          "type": "SELECT",
          "required": true,
          "label": { "tr": "Banka", "en": "Bank" },
          "pii": false,
          "options": [
            { "value": "0010", "label": { "tr": "T.C. ZİRAAT BANKASI A.Ş.", "en": "T.C. ZİRAAT BANKASI A.Ş." } },
            { "value": "0046", "label": { "tr": "AKBANK T.A.Ş.", "en": "AKBANK T.A.Ş." } },
            { "value": "0062", "label": { "tr": "T. GARANTİ BANKASI A.Ş.", "en": "T. GARANTİ BANKASI A.Ş." } }
          ]
        }
      ],
      "splitEligible": false,
      "splitBehavior": null
    }
  ],
  "banks": [
    { "bankCode": "0046", "bankName": "AKBANK T.A.Ş.", "providerCode": "COMPAY" },
    { "bankCode": "0062", "bankName": "T. GARANTİ BANKASI A.Ş.", "providerCode": "COMPAY" },
    { "bankCode": "0010", "bankName": "T.C. ZİRAAT BANKASI A.Ş.", "providerCode": "COMPAY" }
  ],
  "splitEligible": false,
  "splitBehavior": null
}

Always read the provider code and the banks from this response; do not hard-code them in your application. All properties of the field definition: Listing Methods › Method fields.

Bank selection

bankCode is the 4-digit BKM bank code from Lunixi's bank dictionary (e.g. 0062). Show the buyer the bankName of the banks in the banks list and send the chosen bank's bankCode in openBanking.bankCode.

banks[] fieldTypeDescription
bankCodestring4-digit BKM bank code; sent in the request as openBanking.bankCode
bankNamestringBank name you can show the buyer
providerCodestringThe provider the platform would pick for this bank when you do not send providerCode. For information only; you may also choose another connected provider that offers the bank with openBanking.providerCode
  • banks lists the banks open in the Agreement Permissions of your connections, sorted by bank name. A bank open with more than one provider appears once.
  • The bankCode options in the provider's inputFields definition likewise contain only the banks open for that provider. A provider with no open bank is not listed for this method.
  • A code the provider does not support at all gets 400 payment.method.block_invalid at request validation (details.field openBanking.bankCode, details.reason invalid_option).
  • A bank the provider supports but that is not open in any of your connections gets 422 payment.method.bank_not_enabled; the payment does not start and no money moves.
  • The bank is asked only through this selection; the buyer does not choose a bank again on the provider's page.

Banks the provider supports today:

  • Akbank0046
  • Albaraka Türk0203
  • Burgan Bank0125
  • DenizBank0134
  • Fibabanka0103
  • Garanti BBVA0062
  • Halkbank0012
  • Kuveyt Türk0205
  • QNB Finansbank0111
  • TEB0032
  • Türkiye İş Bankası0064
  • Vakıf Katılım0210
  • VakıfBank0015
  • Yapı Kredi0067
  • Ziraat Bankası0010
  • Ziraat Katılım0209

Bank permissions

You set which banks are open in your contract with the provider in the panel, in the Agreement Permissions section of your provider connection.

  • Open Banking banks have their own list; you turn each bank on or off. On a new connection all banks are on, and at least one bank must stay on.
  • This setting applies on every channel: GET /payments/methods, the Checkout Form and the Direct API accept only open banks.
  • If you have more than one connection for the method, each connection has its own list. A bank can be used when it is open in at least one of your connections.

For the Checkout Form you additionally set the order and visibility of the banks, and which provider each bank goes through, in Form Settings; that setting affects only the form → With the Checkout Form.

Choosing the provider

With Open Banking the buyer chooses their bank; they do not need to choose a provider. openBanking.providerCode is optional:

  • If you send providerCode, that provider is used. The chosen bank must be open in at least one of that provider's connections; otherwise you get 422 payment.method.bank_not_enabled.
  • If you do not send providerCode, the platform picks the provider among your connected providers that support the chosen bank and have it open in their Agreement Permissions. With a single candidate that provider is used; with several, the platform's selection order applies. In this case 400 payment.provider.required is not returned.
  • If there is no eligible candidate you get 422 payment.method.bank_not_enabled.
  • The chosen provider is pinned to the payment: on an error the payment does not move to another provider, another method or card. The provider that runs the payment is in the providerCode field of the response and the webhook.

Today the provider of this method is Compay (COMPAY).

With the Checkout Form

In the form, the Checkout Form SDK makes the open banking calls. The code you write is the same as for card payments: create the intent on your server and mount the form on your page → Checkout Form. The method's form-settings group is open_banking; use this name when you narrow the methods with settings.paymentMethods on the intent.

What the buyer sees

Chooses the method

The buyer chooses Open Banking among the payment methods.

Chooses their bank

The form lists the banks enabled in your form settings; the buyer chooses the bank that holds their account and starts the payment. Your form settings decide which provider each bank goes through.

Approves at their bank

The buyer is redirected to their bank's page, signs in and approves the payment order.

Sees the result

When the buyer comes back the result is verified with the provider. If you gave a callbackUrl on the intent, the buyer arrives at your page with the signed result form; otherwise they see Lunixi's result page.

Banks in the form

You manage the banks in the panel under Payment → Form Settings, in the Payment options list of Open Banking → Checkout Form — Payment › Bank rows.

  • You drag the banks into their order in the form and turn each bank on or off for the form with the Show in the form switch.
  • When a bank is open with more than one connected provider, you choose which provider it goes through.
  • Without a setting, all banks open in your Agreement Permissions are sorted by bank name and go through the first provider in the method's provider order.
  • This setting affects only the Checkout Form. GET /payments/methods and Direct API payments are not affected by it; there only the Agreement Permissions apply.

With the Direct API

POST https://api-gateway.lunixi.com/api/v1/payments/direct/payment
Content-Type: application/json

The request carries Step-Up authentication (Bearer token and Ed25519 signature headers; see Authentication) and a required Idempotency-Key header (at most 200 characters); the rules are the same as in Payment — Idempotency.

Method fields

FieldTypeRequiredDescription
paymentMethodstringYesOPEN_BANKING
openBankingobjectYesOpen banking block; its fields are in the rows below
openBanking.bankCodestringYes4-digit code of the bank the buyer chose; one of the banks in the method row's banks list. See Bank selection
openBanking.providerCodestringNoThe provider the bank goes through. Without it the platform picks; see Choosing the provider
callbackUrlstringNohttp or https, at most 2048 characters. On return the buyer's browser arrives at this address with the signed result form. Without it the buyer sees Lunixi's result page
  • The body carries only the openBanking block: another method's block or card, force3D, installment, installmentQuoteToken make the request fail with 400 VALIDATION_ERROR.
  • The order fields (orderId, amount, currency, buyer, basketItems …) are the same for all methods → Payment — Order fields.
  • When your connection requires the identity number, send buyer.identityNumber; see Turkish identity number.

Example request

# See the Authentication page for how the Step-Up signature headers are computed.
curl -X POST https://api-gateway.lunixi.com/api/v1/payments/direct/payment \
  -H "Authorization: Bearer at_test_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: mk_test_sk_..." \
  -H "X-Date: 2026-11-12T09:00:00.000Z" \
  -H "X-Nonce: 6e1b3d5f-7a9c-4e2b-8d0f-1a3c5e7b9d2f" \
  -H "Digest: SHA-256=..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: ORDER-1005-1" \
  -d '{
    "paymentMethod": "OPEN_BANKING",
    "orderId": "ORDER-1005",
    "amount": "250000",
    "currency": "TRY",
    "callbackUrl": "https://merchant.example.com/payments/result",
    "openBanking": { "bankCode": "0062" },
    "basketItems": [{ "id": "ITEM-1", "name": "Service fee", "category1": "Service", "itemType": "VIRTUAL", "price": "250000" }],
    "buyer": { "name": "Ada", "surname": "Yılmaz", "identityNumber": "11111111111", "email": "[email protected]", "gsmNumber": "+905000000000", "city": "Istanbul", "country": "Turkey", "zipCode": "34732", "ip": "203.0.113.10" },
    "billingAddress": { "contactName": "Ada Yılmaz", "address": "Altunizade Mah. Örnek Sok. No: 1", "city": "Istanbul", "country": "Turkey", "zipCode": "34662" }
  }'

Response

{
  "status": "partial",
  "code": "CUSTOMER_ACTION_REQUIRED",
  "message": "…",
  "data": {
    "paymentId": "5b2d7f9a-1c3e-4a6b-8d0f-2e4a6c8b0d1f",
    "orderId": "ORDER-1005",
    "status": "PROCESSING",
    "paymentMethod": "OPEN_BANKING",
    "providerCode": "COMPAY",
    "action": {
      "id": "act_2f4a6c8e0b1d3f5a7c9e1b3d5f7a9c0e",
      "type": "REDIRECT",
      "expiresAt": "2026-11-12T09:30:00.000Z",
      "redirect": { "url": "https://api-gateway.lunixi.com/api/v1/payments/launch/<redirect-token>" }
    }
  },
  "statusCode": 202,
  "requestId": "…"
}
FieldDescription
data.statusPROCESSING: the payment is waiting for the buyer's approval at the bank
action.typeREDIRECT
action.redirect.urlThe address the buyer goes to. See Redirect and return
action.expiresAtLatest time for the buyer to complete the payment (ISO 8601); 30 minutes after the action opens

If the request fails validation or the payment is rejected before the buyer is redirected, the response returns with HTTP 400; see Errors.

Redirect and return

  • Redirect the buyer's browser to action.redirect.url without delay (a browser GET). The address is Lunixi's interstitial page; it sends the buyer on to the provider and the chosen bank.
  • The address is single-use and can be opened for 10 minutes. On a second opening or after it expires the buyer sees an error page; no new redirect address is issued for the same payment.
  • Do not open the address in an iframe; bank pages do not work inside an iframe.
  • The data the buyer brings back from the bank is not the result: the platform queries the result from the provider and closes the payment accordingly.
  • If you gave a callbackUrl, the buyer's browser arrives at that address with an HTML form POST carrying the result. The fields and signature are the same as for the card 3D Secure return → Card — 3D Secure › Signed callback. The status field is success, failure or pending (the result is still being verified).
⚠️

The return form is informational; do not base delivery on it. The buyer's browser may never return to your page. Confirm the order with the payment.captured webhook or GET /payments/:id.

Result

SituationWhat happensWhat to do
The buyer approved at their bankThe payment is CAPTURED, payment.captured is sentShip the order
The buyer did not approve, cancelled, or the bank declinedThe payment is FAILED, payment.failed is sentNo money moved. Offer the buyer a new payment or another method
The buyer did not complete the payment within 30 minutes or closed the pageThe platform asks the provider for the result and settles the payment to its real state; meanwhile the payment may show NEEDS_RECONCILIATIONDo not start a new payment; wait for the webhook
  • While the payment is PROCESSING or NEEDS_RECONCILIATION, do not start a new payment for the same order; the buyer could be charged twice.
  • If the payment is FAILED, start a new payment with a new Idempotency-Key to retry.
  • In the panel the payment details show the bank the payment came from and the account holder's name and IBAN masked. The identity number is not shown.

Turkish identity number

For some merchant categories (e.g. games of chance, balance top-up) the provider requires the buyer's Turkish identity number (T.C. kimlik numarası). In that case you turn on the identity number required setting on your provider connection.

  • When the setting is on, send the buyer's 11-digit identity number with a valid checksum in buyer.identityNumber on every payment. In the Checkout Form this field is read from the buyer data on the intent.
  • If the number is missing or invalid, the payment is rejected before the buyer is redirected to the bank; no money moves.
  • The number is passed only to the provider; it is not shown in responses, webhooks or the panel.

Refunds, voids and pre-authorization

  • Open banking payments cannot be refunded, fully or partially. A refund request is not accepted and no money moves. If you need to pay the buyer back, do so outside Lunixi.
  • The payment cannot be voided; pre-authorization is not supported.

Errors

Error responses use the common error envelope; branch on code, not on message → Error Handling.

SituationResponseWhat to do
No openBanking block, bankCode missing or not in the list400 payment.method.block_invalidFix the details.field field; let the buyer choose the bank from the options
The method is disabled in the panel422 payment.method.disabledEnable the method under Payment → Form Settings
The chosen bank is not open in the Agreement Permissions of any of your connections, or is closed for the providerCode you sent422 payment.method.bank_not_enabledThe payment did not start. Let the buyer choose a bank from the banks list, or turn the bank on under Agreement Permissions in the panel
In the Checkout Form, the bank is turned off for the form or set to another provider in the form settings422 payment.provider.disabled_in_form (details.bankCode)The form offers the buyer the banks enabled in the form; see Banks in the form
The selected provider is not connected422 payment.provider.not_availableCheck the provider connection in the panel
preauth: true was sent422 payment.preauth.unsupported_for_methodSend without preauth
Your connection requires the identity number and buyer.identityNumber is missing or invalid400, payment FAILEDThe buyer was not redirected and no money moved. Fix the request and start again with a new Idempotency-Key
The buyer did not approve or the bank declinedPayment FAILED, payment.failedOffer the buyer another method

Other codes: Payment — Error codes.

Webhooks

EventWhen
payment.capturedThe payment completed; the money reached your account. Ship the order on this event
payment.failedThe payment failed; nothing was charged

The data of the events carries paymentMethod: "OPEN_BANKING" and the provider's providerCode. Delivery, signature verification and retry rules → Webhooks.

Next steps