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
422payment.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. Withpreauth: truethe request gets422payment.preauth.unsupported_for_methodbefore 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[] field | Type | Description |
|---|---|---|
bankCode | string | 4-digit BKM bank code; sent in the request as openBanking.bankCode |
bankName | string | Bank name you can show the buyer |
providerCode | string | The 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 |
bankslists 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
bankCodeoptions in the provider'sinputFieldsdefinition 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
400payment.method.block_invalidat request validation (details.fieldopenBanking.bankCode,details.reasoninvalid_option). - A bank the provider supports but that is not open in any of your connections gets
422payment.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
Fibabanka0103Garanti BBVA0062
Halkbank0012
Kuveyt Türk0205
QNB Finansbank0111TEB0032
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 get422payment.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 case400payment.provider.requiredis not returned. - If there is no eligible candidate you get
422payment.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
providerCodefield 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/methodsand 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/jsonThe 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
| Field | Type | Required | Description |
|---|---|---|---|
paymentMethod | string | Yes | OPEN_BANKING |
openBanking | object | Yes | Open banking block; its fields are in the rows below |
openBanking.bankCode | string | Yes | 4-digit code of the bank the buyer chose; one of the banks in the method row's banks list. See Bank selection |
openBanking.providerCode | string | No | The provider the bank goes through. Without it the platform picks; see Choosing the provider |
callbackUrl | string | No | http 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
openBankingblock: another method's block orcard,force3D,installment,installmentQuoteTokenmake the request fail with400 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": "…"
}| Field | Description |
|---|---|
data.status | PROCESSING: the payment is waiting for the buyer's approval at the bank |
action.type | REDIRECT |
action.redirect.url | The address the buyer goes to. See Redirect and return |
action.expiresAt | Latest 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.urlwithout delay (a browserGET). 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. Thestatusfield issuccess,failureorpending(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
| Situation | What happens | What to do |
|---|---|---|
| The buyer approved at their bank | The payment is CAPTURED, payment.captured is sent | Ship the order |
| The buyer did not approve, cancelled, or the bank declined | The payment is FAILED, payment.failed is sent | No money moved. Offer the buyer a new payment or another method |
| The buyer did not complete the payment within 30 minutes or closed the page | The platform asks the provider for the result and settles the payment to its real state; meanwhile the payment may show NEEDS_RECONCILIATION | Do not start a new payment; wait for the webhook |
- While the payment is
PROCESSINGorNEEDS_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 newIdempotency-Keyto 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.identityNumberon every payment. In the Checkout Form this field is read from thebuyerdata 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.
| Situation | Response | What to do |
|---|---|---|
No openBanking block, bankCode missing or not in the list | 400 payment.method.block_invalid | Fix the details.field field; let the buyer choose the bank from the options |
| The method is disabled in the panel | 422 payment.method.disabled | Enable 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 sent | 422 payment.method.bank_not_enabled | The 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 settings | 422 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 connected | 422 payment.provider.not_available | Check the provider connection in the panel |
preauth: true was sent | 422 payment.preauth.unsupported_for_method | Send without preauth |
Your connection requires the identity number and buyer.identityNumber is missing or invalid | 400, payment FAILED | The 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 declined | Payment FAILED, payment.failed | Offer the buyer another method |
Other codes: Payment — Error codes.
Webhooks
| Event | When |
|---|---|
payment.captured | The payment completed; the money reached your account. Ship the order on this event |
payment.failed | The 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
- Payment — common request, response, actions and error codes
- Listing Methods — method row, provider selection and method fields
- Open Banking Providers — connection details and settings
- Checkout Form — Payment — the flow of non-card methods in the form