Taksit Seçenekleri

Kartın ilk 8 hanesini (BIN) ve hedef terminali göndererek, o terminalde geçerli taksit seçeneklerini ve her taksit için ödeyeceğiniz komisyon oranını sorgularsınız. Bu uç, ödeme oluşturmadan önce kendi checkout’unuzda alıcıya taksit seçenekleri sunmak ve komisyonu satış fiyatına yansıtıp yansıtmayacağınıza karar vermek içindir. Ayrıca, ödeme oluştururken hangi taksit sayılarının kabul edileceğini önceden gösterir; böylece geçersiz bir taksit yüzünden ödeme sonrasında hata almazsınız.

Alıcı kartını girmeden önce (örn. sepet ekranında) terminalinizde hangi kart profilleriyle taksit mümkün olduğunu görmek isterseniz, bu ucun BIN istemeyen kardeşine bakın: Taksit Genel Görünümü.

POST /v1/installment-options
Authorization: Bearer ldg_live_…
Content-Type: application/json

İstek gövdesi

{
  "bin": "41551400",
  "terminalId": "trm_3Kd9x"
}

Alan	Zorunlu	Açıklama
bin	Evet	Kartın ilk 8 hanesi — tam PAN değil. Tam 8 hane olmalıdır; 6-7 hane ya da 9 ve üzeri hane validation_error (400) ile reddedilir.
terminalId	Evet	Sorgulanacak terminal. Size ait ve aktif olmalıdır; aksi halde terminal_not_allowed döner.
baseAmount	Hayır	Anapara (satış) tutarı, kuruş cinsinden tamsayı (≥1). Gönderirseniz yanıttaki her seçenek bu tutara dayalı otoriter bir tutar kırılımı taşır; göndermezseniz yanıt bugünkü gibi yalnızca oran matrisidir.
customerCommissionShareBps	Hayır	Müşterinin üstleneceği komisyon payı, baz puan tamsayı (0-10000; %100 → 10000). Yalnızca baseAmount ile birlikte anlamlıdır. Göndermezseniz varsayılan taban bağlıdır: gross tabanda pay 0 kabul edilir (komisyon alıcıya yansımaz); net tabanlı bir terminalde ise pay 10000 (tam yansıtma) uygulanır — net taban tanım gereği komisyonun tamamını alıcıya yansıtır.

Neden tam 8 hane

6 ya da 7 hane göndermeyin: bin alanı tam 8 haneli bir kalıpla doğrulanır, kısa ya da uzun bir girdi markayı sessizce “bilinmiyor” (cardBrand: null) olarak yanıtlamaz — bunun yerine validation_error (400) ile reddedilir. Bu guard’ın amacı, bu uçtan aldığınız önizlemenin sessizce yanlış bir markaya çözülüp aynı kartla ödeme oluşturduğunuzda alacağınız gerçek sonuçtan ayrışmasını önlemektir. Bu ucu, kartın 8. hanesi girildiğinde çağırın (6. hanede değil).

customerCommissionShareBps tek başına gönderilemez

customerCommissionShareBps, bir paylaşım oranıdır ve yalnızca bir taban tutarına (baseAmount) uygulanabilir. baseAmount göndermeden yalnızca customerCommissionShareBps gönderirseniz istek 400 validation_error ile reddedilir; bu alan sessizce yok sayılmaz.

Yanıt

200 OK:

{
  "cardBrand": "world",
  "cardFamily": "credit",
  "cardBank": "Örnek Bank",
  "options": [
    { "installmentCount": 1, "rateBps": 250, "fixedFee": null,
      "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null },
    { "installmentCount": 3, "rateBps": 180, "fixedFee": null,
      "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null },
    { "installmentCount": 6, "rateBps": 220, "fixedFee": null,
      "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null }
  ],
  "commissionBasis": "gross"
}

Alan	Açıklama
cardBrand	Kartın taksit programı/markası (örn. world, paraf, bonus, maximum, axess, advantage, cardfinans, saglam, vkart, bankkart). BIN çözülemezse ya da marka bilinmiyorsa null.
cardFamily	Kart ailesi (credit, debit, prepaid, foreign). BIN hiç çözülemediyse null.
cardBank	Kartı çıkaran banka adı (varsa); PII değildir. Bilinmiyorsa null.
options	Bu kart × terminal ikilisinde gerçekten tahsil edilebilir taksit × oran listesi, taksit sayısına göre artan sıralı. Peşin (installmentCount: 1) dahildir (terminalin efektif taksit kümesi kapsıyorsa). Liste boş dönebilir; bkz. Boş options listesi.
commissionBasis	Terminalinizin komisyon tabanı, gross ya da net. İstekte baseAmount gönderip göndermediğinizden bağımsız her zaman döner. Bkz. Fiyatlama kılavuzu.
options[].installmentCount	Taksit sayısı; tek çekim için 1.
options[].rateBps	Bu taksit için toplam (satış) komisyon oranı, baz puan tamsayı (%2,5 → 250).
options[].fixedFee	Bu taksit için sabit ücret, kuruş tamsayı; yoksa null.
options[].baseAmount	İstekte gönderdiğiniz baseAmount; her seçenekte aynıdır. İstekte baseAmount yoksa null.
options[].commissionAmount	Bu taksit için hesaplanan toplam komisyon (kuruş), terminalinizin commissionBasis’ine göre hesaplanır. İstekte baseAmount yoksa null.
options[].customerShareAmount	Bu komisyonun customerCommissionShareBps oranına göre alıcıya yansıyan payı (kuruş); totalAmount − baseAmount’a eşittir. İstekte baseAmount yoksa null.
options[].totalAmount	Alıcıdan çekilecek nihai tutar (kuruş). Otoriterdir; bkz. baseAmount ile otoriter tutar kırılımı. İstekte baseAmount yoksa null.

Terminalin PSP’si kart için taksit desteklemiyorsa ya da marka bilinmiyorsa

options yalnızca peşin (installmentCount: 1) satırını içerir (efektif küme kapsıyorsa). Bu durum; kartın markası PSP’nin taksit programına dahil değilse, marka çözülemiyorsa ya da PSP taksidi yalnızca kendi ihraç ettiği kartlarla sınırlıyorsa ve kart o PSP tarafından ihraç edilmemişse ortaya çıkar. Bu durumda checkout’unuzda taksit seçeneği sunmayın; yalnızca peşin tahsilat mümkündür.

Terminalin efektif taksit kümesi daraltılmış olabilir

Hesabınızda bir terminalin kabul ettiği taksit sayıları, bankanın izin verdiği tavanın bir alt kümesine daraltılmış olabilir (bu yapılandırma Lydia Gate Merchant Panel’de yapılır). Böyle bir durumda options, yalnızca bu daraltılmış kümedeki taksit sayılarını listeler. Bir ödeme linki oluştururken kendi allowedInstallmentCounts kısıtınızı eklerseniz, alıcıya sunulan nihai küme kartın taksit markasının kapsamı, terminalin (daraltılmış olabilecek) kümesi ve link kısıtının kesişimidir.

PSP maliyeti/marjı dönmez

rateBps ve fixedFee, terminalinizde geçerli toplam (Lydia Gate’e ödeyeceğiniz) satış komisyon oranını taşır. Lydia Gate’in kendi maliyet/marj yapısı bu yanıtta hiçbir zaman yer almaz.

baseAmount ile otoriter tutar kırılımı

İstekte baseAmount gönderirseniz elle hesap yapmanıza gerek kalmaz: options içindeki her seçenek, o taksit için tam tutar kırılımını hazır taşır.

{
  "bin": "41551400",
  "terminalId": "trm_3Kd9x",
  "baseAmount": 10000,
  "customerCommissionShareBps": 0
}

200 OK:

{
  "cardBrand": "world",
  "cardFamily": "credit",
  "cardBank": "Örnek Bank",
  "options": [
    { "installmentCount": 1, "rateBps": 250, "fixedFee": null,
      "baseAmount": 10000, "commissionAmount": 250, "customerShareAmount": 0, "totalAmount": 10000 },
    { "installmentCount": 3, "rateBps": 180, "fixedFee": null,
      "baseAmount": 10000, "commissionAmount": 180, "customerShareAmount": 0, "totalAmount": 10000 },
    { "installmentCount": 6, "rateBps": 220, "fixedFee": null,
      "baseAmount": 10000, "commissionAmount": 220, "customerShareAmount": 0, "totalAmount": 10000 }
  ],
  "commissionBasis": "gross"
}

Bu örnekte customerCommissionShareBps 0 gönderildiği için komisyonun tamamı size aittir: customerShareAmount sıfırdır ve totalAmount, gönderdiğiniz baseAmount’a eşit kalır. Pozitif bir customerCommissionShareBps verirseniz bu pay customerShareAmount’a yansır ve totalAmount, baseAmount’ın üzerine çıkar — hesap terminalinizin commissionBasis’ine göre otomatik yapılır.

totalAmount otoriterdir

totalAmount’ı doğrudan POST /v1/payments’ın amount alanına gönderebilirsiniz. Bu değeri kendiniz yeniden hesaplarsanız yuvarlama farkı kendi net tutarınıza yansır; bu ucun döndürdüğü totalAmount her zaman doğru sonucu verir.

Yanıt additive, ama byte-eşit değil

commissionBasis artık her yanıtta yer alır ve her seçenekte dört yeni alan (baseAmount, commissionAmount, customerShareAmount, totalAmount) bulunur. baseAmount göndermediğiniz sürece bu dört alan null döner ve mevcut entegrasyonunuz etkilenmez — ama yanıt artık eskisiyle birebir aynı değildir; bilinmeyen/null alanları yok sayan bir JSON ayrıştırıcı kullanıyorsanız bu bir sorun oluşturmaz.

Boş options listesi: bu kartla ödeme alamazsınız

options boş bir dizi dönebilir; bu, peşin (installmentCount: 1) dâhil hiçbir seçeneğin bu kart × terminal ikilisinde sunulmadığı anlamına gelir. En yaygın nedeni, terminalinizin bağlı olduğu banka bağlantısının kartın tipini desteklememesidir; pratikte bunu en çok yurt dışı ihraçlı kartlarda (cardFamily: "foreign") görürsünüz. (Terminalinizin efektif taksit kümesi peşini kapsamıyorsa ve kart taksite de uygun değilse liste yine boş kalır.)

Boş liste geldiğinde bu kartla bu terminalde ödeme almayı denemeyin; alıcıdan başka bir kart isteyin. Yine de denerseniz ödeme virtual_pos_card_type_not_supported (422) ya da installment_not_allowed (422) ile reddedilir — bkz. Hata Kodları. Kart tipi desteklenmediği için alınan ret, ödemenin kart-deneme hakkından düşer; bkz. Ödeme Akışı.

Bu uç ile ödeme oluşturma arasındaki ilişki

Bu ucun döndürdüğü her installmentCount, aynı terminal ve BIN ile ödeme oluştururken (POST /v1/payments’ın installment alanı) aynı rateBps/fixedFee ile kabul edilir. Döndürmediği bir taksit sayısını installment olarak gönderirseniz, terminalinizin taksit izni yoksa create anında, aksi halde (kartın markasına bağlı nedenlerle) ödemenin 3D devri sırasında installment_not_allowed (422) alırsınız — bkz. Hata Kodları: taksit uyumsuzluğu.

Liste karta özgüdür: terminalinizin genel olarak izin verdiği bir taksit sayısı, belirli bir kart için listede yer almayabilir. Bu yüzden checkout’unuzdaki taksit menüsünü sabit kodlamayın; her kart için bu ucu çağırıp dönen listeyi olduğu gibi gösterin. Listede gördüğünüz her taksit gerçekten ödenebilir, görmedikleriniz ödenemez.

Fiyatlama kılavuzu: komisyonu satış fiyatınıza nasıl yansıtırsınız

Bu uç size, taksit başına terminalinizde geçerli toplam komisyon oranını verir. Komisyonun hangi tutar üzerinden hesaplandığı terminalinizin komisyon tabanına bağlıdır: yanıttaki commissionBasis alanı (gross ya da net) bunu size bildirir. gross tabanda (bugünkü varsayılan davranış) oran alıcıdan çekilen tutar üzerinden hesaplanır; net tabanda oran anapara üzerinden hesaplanır ve müşterinin üstlendiği pay anaparanın üstüne eklenir. Bu bilgiyle iki seçeneğiniz vardır:

1. Komisyonu siz üstlenirsiniz: alıcıdan taksit sayısından bağımsız aynı tutarı (amount) tahsil edersiniz; Lydia Gate komisyonunu kendi net tutarınızdan düşer.
2. Komisyonu alıcıya yansıtırsınız (vade farkı): taksitli satışta alıcıdan, komisyonu karşılayacak şekilde daha yüksek bir tutar tahsil edip bu tutarı POST /v1/payments’ın amount alanına gönderirsiniz.

Bu hesabı elle yapmanıza gerek yok: isteğe baseAmount (ve isteğe bağlı customerCommissionShareBps) eklerseniz bu ucun kendisi otoriter bir tutar kırılımı döner ve doğrudan totalAmount’ı gönderebilirsiniz. Aşağıdaki manuel hesap, gross tabanlı bir terminalde komisyonu birebir yansıtan en basit politikayı, kendi hesabınızı yapmak isterseniz nasıl uygulayacağınızı gösterir; oran anaparadan hesaplandığından bu formül net tabanlı bir terminalde geçerli değildir — o durumda otoriter kırılımı kullanın.

Vade farkı oranını kendi ticari politikanıza göre serbestçe belirlersiniz; rateBps yalnızca sizin ödeyeceğiniz komisyonu bildirir, alıcıya yansıtacağınız tutarı sınırlamaz.

Örnek: tamsayı-kuruş hesabı (float yok, gross taban)

Peşin satış fiyatınız 100,00 TL (amount = 10000 kuruş) olsun ve alıcı 3 taksit seçsin; bu uçtan installmentCount: 3 için rateBps: 180 (%1,80) döndüğünü varsayalım. Komisyonu vade farkı olarak birebir yansıtmaya karar verirseniz:

vadeFarki = (pesinTutar * rateBps) / 10000   // tamsayı bölme: 10000 * 180 / 10000 = 180 kuruş
brutTutar = pesinTutar + vadeFarki             // 10000 + 180 = 10180 kuruş

POST /v1/payments çağrınızın amount alanına 10180 gönderirsiniz.

Yuvarlama: en yakın kuruşa (half-up)

Lydia Gate komisyonu en yakın kuruşa yuvarlar (half-up; tam 0,5 kuruş yukarı). Kendi vade farkı hesabınızda float/ondalık kullanmayın; yukarıdaki gibi tamsayı-kuruş aritmetiği tercih edin — float çarpımı yuvarlama hatası üretebilir. Bkz. Tutar ve Para Birimi.

Hız limiti

Partner başına dakikalık bir hız limiti uygulanır (checkout’unuzda BIN girildikçe sık çağrılabilir; yine de BIN-tarama/probing’e karşı bir tavan vardır). Aşımda rate_limited (429) alırsınız; bu uçta yanıt Retry-After başlığı taşımaz — kısa bir süre bekleyip tekrar deneyin.

Olası hatalar

Kod	HTTP	Sebep
validation_error	400	bin tam 8 hane değil ya da terminalId boş/eksik.
terminal_not_allowed	403	Terminal size ait değil, pasif ya da kartın ailesi bu terminalde izinli değil.
rate_limited	429	Çok fazla istek: hız limiti aşıldı.

Tam liste: Hata Kodları.

Nadir durum: yapılandırma eksikliği

Terminalinizde ilgili kart tipi için hiç peşin komisyon oranı tanımlı değilse (örn. eksik yapılandırma), bu uç 500 ile commission_rate_not_found döner. Bu bir istemci hatası değildir; oluşursa destek ekibiyle iletişime geçin.