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.

POST /v1/installment-options
Authorization: Bearer ptk_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.

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).

Yanıt

200 OK:

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

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.
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.

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.

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 (virtual POS) 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. 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 brüt tutar tahsil edip bu tutarı POST /v1/payments’ın amount alanına gönderirsiniz. Lydia Gate komisyonu her durumda gönderdiğiniz brüt amount üzerinden hesaplanır — vade farkını brüte eklemeniz komisyonun hesaplanma biçimini değiştirmez, yalnızca komisyonun üzerinden hesaplandığı tabanı büyütür.

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. Aşağıdaki örnek, komisyonu birebir yansıtan en basit politikayı gösterir.

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

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; yanıt bir Retry-After başlığı taşıyabilir.

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.