Taksit Genel Görünümü

Alıcı henüz kartını girmeden — örneğin sepet ya da ödeme öncesi bir özet ekranında — hedef terminali göndererek o terminalde o anda geçerli tüm taksit seçeneklerini kart profili gruplarıyla ve her taksit sayısı için en pahalı seçeneği sorgularsınız. Bu uç, Taksit Seçenekleri ucunun kart bilgisi (BIN) istemeyen kardeşidir: kartın markasını/tipini henüz bilmediğiniz an “bu terminalde hangi kart tipleriyle taksit mümkün” sorusuna cevap verir.

Bu uç kartı görmediğinden, döndürdüğü gruplardan hangisinin alıcının kartına uygulanacağını kesin olarak söyleyemez — yalnızca terminalinizde teorik olarak mümkün olan tüm profilleri listeler. Alıcı kartın ilk 8 hanesini girdiğinde, kesin sonuç için Taksit Seçenekleri ucuna geçin.

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

İstek gövdesi

{
  "terminalId": "trm_3Kd9x"
}

Alan	Zorunlu	Açıklama
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 her seçenek otoriter bir tutar kırılımı taşır ve maximums’taki “en pahalı” ölçütü tutara döner; göndermezseniz ölçüt orandır.
customerCommissionShareBps	Hayır	Müşterinin üstleneceği komisyon payı, baz puan tamsayı (0-10000). Yalnızca baseAmount ile birlikte anlamlıdır. Varsayılan davranış Taksit Seçenekleri ile aynıdır: gross tabanda 0, net tabanlı bir terminalde 10000 (tam yansıtma).

customerCommissionShareBps tek başına gönderilemez

baseAmount göndermeden yalnızca customerCommissionShareBps gönderirseniz istek 400 validation_error ile reddedilir; bu alan sessizce yok sayılmaz.

Yanıt

200 OK:

{
  "commissionBasis": "gross",
  "maximums": [
    { "option": { "installmentCount": 1, "rateBps": 250, "fixedFee": null,
        "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null },
      "source": { "cardType": "credit", "onUs": false, "cardBrand": null } },
    { "option": { "installmentCount": 3, "rateBps": 180, "fixedFee": null,
        "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null },
      "source": { "cardType": null, "onUs": null, "cardBrand": "paraf" } },
    { "option": { "installmentCount": 6, "rateBps": 220, "fixedFee": null,
        "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null },
      "source": { "cardType": null, "onUs": null, "cardBrand": "paraf" } }
  ],
  "optionGroups": [
    { "cardType": "credit", "onUs": false, "cardBrand": null, "onUsRequired": null,
      "options": [ { "installmentCount": 1, "rateBps": 250, "fixedFee": null,
          "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null } ] },
    { "cardType": "credit", "onUs": true, "cardBrand": null, "onUsRequired": null,
      "options": [ { "installmentCount": 1, "rateBps": 200, "fixedFee": null,
          "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null } ] },
    { "cardType": "debit", "onUs": false, "cardBrand": null, "onUsRequired": null,
      "options": [ { "installmentCount": 1, "rateBps": 150, "fixedFee": 50,
          "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null } ] },
    { "cardType": "debit", "onUs": true, "cardBrand": null, "onUsRequired": null,
      "options": [ { "installmentCount": 1, "rateBps": 150, "fixedFee": 50,
          "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null } ] },
    { "cardType": null, "onUs": null, "cardBrand": "paraf", "onUsRequired": true,
      "options": [
        { "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 }
      ] }
  ]
}

Bu örnekte terminal kredi ve banka kartlarını kabul ediyor; kredi kartında terminalin bağlı olduğu banka kendi kartına (onUs: true) daha düşük bir oran (200) uyguluyor, diğer bankaların kartlarına (onUs: false) 250 uyguluyor. paraf markalı kartlarda taksit yalnızca terminalin bağlı olduğu bankanın kendi kartlarında açılıyor (onUsRequired: true).

Alan	Açıklama
commissionBasis	Terminalinizin komisyon tabanı, gross ya da net. baseAmount gönderip göndermediğinizden bağımsız her zaman döner.
maximums	Taksit sayısı başına TEK en pahalı seçenek, onu üreten kart profiliyle (source) birlikte; installmentCount’a göre artan sıralı. Ölçüt aşağıda açıklanmıştır.
maximums[].option	Taksit×oran satırı — Taksit Seçenekleri ucunun options[] satırıyla birebir aynı şekildedir (installmentCount/rateBps/fixedFee + baseAmount gönderildiyse otoriter kırılım).
maximums[].source	O satırı üreten kart profili (cardType/onUs/cardBrand); aşağıdaki profil tanımına bakın.
optionGroups	Terminalinizde uygulanabilir her kart profili için ayrı bir grup; boş grup asla dönmez.
optionGroups[].cardType	Kart tipi (credit, debit, prepaid, foreign); bu boyut grup anahtarında ayrıştırılmıyorsa null (marka gruplarında olduğu gibi).
optionGroups[].onUs	Kart, terminalin bağlı olduğu bankanın kendi kartı mı (true) yoksa başka bir bankanın kartı mı (false); bu boyut ayrıştırılmıyorsa null.
optionGroups[].cardBrand	Taksit markası (world, paraf, bonus, maximum, axess, advantage, cardfinans, saglam, vkart, bankkart); marka bu grupta belirleyici değilse null.
optionGroups[].onUsRequired	Yalnız marka gruplarında (cardType: null) dolu — bkz. onUsRequired bağlayıcı olmayan bir ipuçudur.
optionGroups[].options	O profildeki taksit×oran satırları, installmentCount artan sıralı.

DEBIT/PREPAID/FOREIGN’da marka oranı belirlemeyebilir

Bir marka grubunun cardType’ı debit, prepaid ya da foreign ise marka yalnızca hangi taksitlerin sunulacağını belirler — uygulanan oran markadan değil kartın tipinden gelebilir. Bu durumda aynı taksit sayısı hem markalı hem markasız grupta görünür ve oranları eşittir; ikisini de gösterebilirsiniz.

“En pahalı” nasıl belirlenir

maximums’taki her taksit sayısı için ölçüt isteğinize göre değişir:

• baseAmount GÖNDERDİYSENİZ: en yüksek customerShareAmount (≡ totalAmount) kazanır.
• baseAmount GÖNDERMEDİYSENİZ: en yüksek rateBps kazanır; eşitlik varsa büyük fixedFee kazanır (fixedFee satır bazında değişebildiğinden bu ölçüt tutar-bağımsız bir yaklaşıklıktır).

onUsRequired bağlayıcı olmayan bir ipuçudur

onUsRequired: true, “bu markanın taksitleri yalnızca terminalinizin bağlı olduğu bankanın kendi kartlarında açılır” anlamına gelir — ama bağlayıcı değildir ve yok sayılabilir. Kartın gerçekten uygun olup olmadığını kesin olarak yalnızca kart bilgisi girildikten sonra Taksit Seçenekleri ucundan öğrenirsiniz; checkout’unuzda bu alanı yalnızca “yalnızca [bankanın] kendi kartlarında” tarzında bir bilgilendirme dipnotu göstermek için kullanabilirsiniz, taksit menüsünü bu alana göre önceden daraltmayın.

Kapsama garantisi ve bilinmeyen BIN’ler

Bu ucun döndürdüğü her kart profili grubu, Taksit Seçenekleri ucunun çözümlenebilen bir BIN ile döndürebileceği her seçeneği kapsar ve o taksit sayısı için maximums’ı aşmaz. Başka bir deyişle: kartın BIN’i sistemimizde tanımlıysa, o kart için BIN’li uçtan alacağınız her satır, burada ilgili profil grubunda aynı değerlerle yer alır.

Tek istisna: kartın BIN’i tanımlı değilse

Kartın BIN’i veri tabanımızda tanımlı değilse, BIN’li uç bu kartı kredi kartı olarak varsayar ve yalnızca terminalin bağlı olduğu bankanın kendi kartı olmadığını varsayarak (onUs: false) peşin oranı döndürür. Bu genel görünüm ucu, kartı görmediğinden bu varsayımı temsil etmez — yani bu satır burada ayrıca listelenmez. Kartın BIN’i tanımlıysa ve terminaliniz kredi kartı kabul ediyorsa bu iki satır çoğunlukla örtüşür, ama bu bir garanti değildir.

Boş liste: bu terminalde henüz hiçbir kart profili sunulamıyor

maximums ve optionGroups ikisi de boş dizi dönebilir — bu terminalde hiçbir kart profiliyle taksit (peşin dâhil) sunulamadığı anlamına gelir. En yaygın nedenler: terminalinizin bağlı olduğu banka bağlantısı aktif değil, terminalinizin komisyon tabanı net ama net tabanın çalışma koşulları (doğrudan-tahsilat bağlantısı + bankaya komisyon bildirimi) o anda sağlanmıyor — bu durumda BIN’li uç da boş döner; not: net tabanda kısmi customerCommissionShareBps göndermek boş liste değil, daima 422 commission_share_not_applicable üretir (bkz. Hata Kodları) — ya da terminalinizde hiçbir kart ailesine izin verilmemiş. Boş yanıt geldiğinde checkout’unuzda taksit seçeneği sunmayın.

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

İstekte baseAmount gönderirseniz elle hesap yapmanıza gerek kalmaz — Taksit Seçenekleri ucundaki AYNI kırılım mantığı burada da geçerlidir: her seçenek commissionAmount/customerShareAmount/totalAmount alanlarını taşır ve totalAmount otoriterdir.

{
  "terminalId": "trm_3Kd9x",
  "baseAmount": 10000,
  "customerCommissionShareBps": 10000
}

200 OK (yukarıdaki senaryonun aynısı, baseAmount = 10000 ve customerCommissionShareBps = 10000 ile):

{
  "commissionBasis": "gross",
  "maximums": [
    { "option": { "installmentCount": 1, "rateBps": 250, "fixedFee": null,
        "baseAmount": 10000, "commissionAmount": 256, "customerShareAmount": 257, "totalAmount": 10257 },
      "source": { "cardType": "credit", "onUs": false, "cardBrand": null } },
    { "option": { "installmentCount": 3, "rateBps": 180, "fixedFee": null,
        "baseAmount": 10000, "commissionAmount": 183, "customerShareAmount": 184, "totalAmount": 10184 },
      "source": { "cardType": null, "onUs": null, "cardBrand": "paraf" } },
    { "option": { "installmentCount": 6, "rateBps": 220, "fixedFee": null,
        "baseAmount": 10000, "commissionAmount": 225, "customerShareAmount": 225, "totalAmount": 10225 },
      "source": { "cardType": null, "onUs": null, "cardBrand": "paraf" } }
  ],
  "optionGroups": [
    { "cardType": "credit", "onUs": false, "cardBrand": null, "onUsRequired": null,
      "options": [ { "installmentCount": 1, "rateBps": 250, "fixedFee": null,
          "baseAmount": 10000, "commissionAmount": 256, "customerShareAmount": 257, "totalAmount": 10257 } ] },
    { "cardType": "credit", "onUs": true, "cardBrand": null, "onUsRequired": null,
      "options": [ { "installmentCount": 1, "rateBps": 200, "fixedFee": null,
          "baseAmount": 10000, "commissionAmount": 204, "customerShareAmount": 205, "totalAmount": 10205 } ] },
    { "cardType": "debit", "onUs": false, "cardBrand": null, "onUsRequired": null,
      "options": [ { "installmentCount": 1, "rateBps": 150, "fixedFee": 50,
          "baseAmount": 10000, "commissionAmount": 203, "customerShareAmount": 204, "totalAmount": 10204 } ] },
    { "cardType": "debit", "onUs": true, "cardBrand": null, "onUsRequired": null,
      "options": [ { "installmentCount": 1, "rateBps": 150, "fixedFee": 50,
          "baseAmount": 10000, "commissionAmount": 203, "customerShareAmount": 204, "totalAmount": 10204 } ] },
    { "cardType": null, "onUs": null, "cardBrand": "paraf", "onUsRequired": true,
      "options": [
        { "installmentCount": 3, "rateBps": 180, "fixedFee": null,
          "baseAmount": 10000, "commissionAmount": 183, "customerShareAmount": 184, "totalAmount": 10184 },
        { "installmentCount": 6, "rateBps": 220, "fixedFee": null,
          "baseAmount": 10000, "commissionAmount": 225, "customerShareAmount": 225, "totalAmount": 10225 }
      ] }
  ]
}

Yuvarlama ve gross-up formülü Taksit Seçenekleri: Fiyatlama kılavuzu ile aynıdır.

Doğrudan-tahsilat (direct) terminallerde de tam kapsama

Terminaliniz doğrudan-tahsilat (direct) modundaysa bu uç yine size uygulanabilir her kart profilini döndürür; markalı gruplar terminalinizin bağlı olduğu banka bağlantısında tanımlı her marka için (yalnızca terminalinizin taksit programına dahil olanlar için değil) kurulur, çünkü doğrudan-tahsilatta oranlar farklı bir kaynaktan hesaplanır. Peşin (tek çekim) satırı, tıpkı havuz modelinde olduğu gibi, yalnızca terminaliniz tek çekimi destekliyorsa (1 efektif taksit kümenizdeyse) üretilir; taksit satırları yalnızca ilgili marka için taksit izniniz varsa eklenir. Kapsama garantisi burada da geçerlidir.

Hız limiti

Bu uç, Taksit Seçenekleri ile AYNI paylaşılan hız limiti kovasını kullanır — partner başına dakikalık tavan iki uç arasında ortaktır. Aşımda rate_limited (429) alırsınız; bu uçta da yanıt Retry-After başlığı taşımaz.

Olası hatalar

Kod	HTTP	Sebep
validation_error	400	terminalId boş/eksik · baseAmount < 1 · customerCommissionShareBps aralık dışı ya da baseAmount olmadan gönderildi.
terminal_not_allowed	403	Terminal size ait değil ya da pasif.
commission_share_not_applicable	422	Terminalinizin komisyon tabanı net ve kısmi bir customerCommissionShareBps gönderdiniz — net taban tanım gereği komisyonu tam yansıtır; alanı hiç göndermemek ya da 10000 göndermek kabul edilir.
rate_limited	429	Çok fazla istek: hız limiti aşıldı.

Tam liste: Hata Kodları.

İlgili

• Taksit Seçenekleri — kart bilgisi (BIN) girildikten sonra kesin taksit×oran sorgusu.
• Ödeme Oluşturma — taksit sayısını ve nihai tutarı ödeme oluştururken gönderirsiniz.