Taksit ve Toplam Tutar Sorgusu

Bu sayfa kartın ilk 8 hanesiyle taksit seçeneklerini ve toplam tutarı sorgulamayı anlatır. Komisyon kart tipine ve taksite göre değiştiği için bu sorgu her ödemeden önce yapılır.

Neden gerekli

Belediye modelinde komisyonu kart sahibi öder. Komisyon anaparanın üstüne eklenir. Oran kartın tipine, kartı çıkaran bankaya ve taksit sayısına göre değişir. Bu yüzden kart sahibinden çekilecek toplam tutar kart görülmeden bilinemez. Bu uç, kartın ilk 8 hanesine göre geçerli taksit seçeneklerini ve her seçenek için toplam tutarı döner. Uç POST isteğiyle çağrılır.

Bu uç aynı zamanda ö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.

Kart henüz girilmeden genel bir taksit tablosu göstermek isterseniz BIN istemeyen uca bakın: Kartsız Taksit Görünümü.

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

İstek

{
  "bin": "54308115",
  "terminalId": "trm_3Kd9x",
  "baseAmount": 15000
}

Alan	Zorunlu	Anlamı
bin	Evet	Kartın ilk 8 hanesi. Tam kart numarası değil. Tam 8 hane olmalıdır. 6 ya da 7 hane ile 9 ve üzeri hane 400 ve validation_error ile reddedilir.
terminalId	Evet	Sorgulanacak terminal. Size ait ve aktif olmalıdır. Aksi halde terminal_not_allowed döner.
baseAmount	Her zaman gönderin	Anapara, kuruş cinsinden tamsayı. En az 1. API tanımı bu alanı isteğe bağlı sayar. Belediye akışında toplam tutarı bu uçtan aldığınız için her zaman gönderin. Göndermezseniz yanıt yalnız oran listesidir ve tutar alanları null döner.

Dikkat

6 ya da 7 hane göndermeyin. Kısa ya da uzun bir bin değeri markayı sessizce bilinmiyor saymaz. İstek 400 ve validation_error ile reddedilir. Bu kural, önizleme ile gerçek sonucun farklı çıkmasını önler. Bu ucu kartın 8. hanesi girildiğinde çağırın.

Yanıt

200 OK:

{
  "cardBrand": "paraf",
  "cardFamily": "credit",
  "cardBank": "Örnek Banka",
  "options": [
    { "installmentCount": 1, "rateBps": 375, "fixedFee": null,
      "baseAmount": 15000, "commissionAmount": 563, "customerShareAmount": 563, "totalAmount": 15563 },
    { "installmentCount": 3, "rateBps": 525, "fixedFee": null,
      "baseAmount": 15000, "commissionAmount": 788, "customerShareAmount": 788, "totalAmount": 15788 }
  ],
  "commissionBasis": "net"
}

Alan	Anlamı
cardBrand	Kartın taksit programı. Değerler: world, paraf, bonus, maximum, axess, advantage, cardfinans, saglam, vkart, bankkart. BIN çözülemezse ya da marka bilinmiyorsa null.
cardFamily	Kart ailesi: credit kredi kartı, debit banka kartı, prepaid ön ödemeli kart, foreign yurt dışı kart. BIN çözülemediyse null.
cardBank	Kartı çıkaran bankanın adı. Bilinmiyorsa null. Kişisel veri değildir.
options	Bu kart ve terminal için gerçekten tahsil edilebilir taksit seçenekleri. Taksit sayısına göre artan sıralıdır. Tek çekim satırı installmentCount: 1 ile gelir. Liste boş dönebilir. Ayrıntı: Boş liste.
commissionBasis	Komisyon tabanı. Belediye terminallerinde her zaman net döner. Bu, komisyonun anaparanın üstüne eklendiği anlamına gelir.
options[].installmentCount	Taksit sayısı. Tek çekim için 1.
options[].rateBps	Bu taksit için anapara üzerinden uygulanan komisyon oranı, baz puan tamsayı. Baz puan, yüzdenin yüzde biridir. %3,75 → 375.
options[].fixedFee	Bu taksit için sabit ücret, kuruş tamsayı. Yoksa null.
options[].baseAmount	İstekte gönderdiğiniz anapara. Her satırda aynıdır.
options[].commissionAmount	Bu taksit için hesaplanan komisyon, kuruş. Ödemede bankaya bildirilen tutar budur.
options[].customerShareAmount	Komisyonun kart sahibine yansıyan payı, kuruş. Belediye modelinde komisyonun tamamıdır. totalAmount − baseAmount değerine eşittir.
options[].totalAmount	Kart sahibinden çekilecek toplam tutar, kuruş. Bu değer kesindir. Ödeme oluştururken amount alanına bu değeri yazarsınız.

Not

Kartın markası bankanın taksit programında değilse ya da marka çözülemiyorsa options yalnız tek çekim satırını içerir. Bu durumda kart sahibine taksit seçeneği sunmayın. Yalnız tek çekim mümkündür.

Not

Terminalinize tanımlı taksit sayıları bankanın izin verdiği tavandan dar olabilir. Bu tanımı LydiaGate yapar. options yalnız tanımlı kümedeki taksit sayılarını listeler. Taksit sayısı eklemek için LydiaGate’e başvurun.

Toplam tutar kesindir

totalAmount değerini doğrudan POST /v1/payments isteğinin amount alanına yazın. Bu değeri kendiniz yeniden hesaplamayın. LydiaGate gelen amount değerini komisyon dahil toplam sayar ve komisyonu bu tutardan geri çıkarır. Kendi hesabınızdaki bir yuvarlama farkı kurumunuzun hesabına geçen anaparayı değiştirir.

Tek çekim örneği

Anapara 150,00 TL ve tek çekim oranı %3,75 olsun.

Kalem	Hesap	Kuruş
Anapara	istekten	15000
Komisyon	15000 × 375 / 10000 = 562,5 → en yakın kuruşa, yarım yukarı	563
Toplam	15000 + 563	15563

Kart sahibinden 155,63 TL çekilir. Bankaya 5,63 TL komisyon bildirilir. Kurumunuzun hesabına 150,00 TL geçer.

Taksitli örnek

Aynı anapara ve 3 taksit için oran %5,25 olsun.

Kalem	Hesap	Kuruş
Anapara	istekten	15000
Komisyon	15000 × 525 / 10000 = 787,5 → en yakın kuruşa, yarım yukarı	788
Toplam	15000 + 788	15788

Kart sahibinden 3 taksitte toplam 157,88 TL çekilir. Taksit tutarlarını kart sahibinin bankası belirler. Kurumunuzun hesabına yine 150,00 TL geçer.

Boş liste: bu kartla ödeme alınamaz

options boş bir liste dönebilir. Bu, tek çekim dahil hiçbir seçeneğin bu kart ve terminal için sunulmadığı anlamına gelir. Neden terminalin taksit izinleri, banka bağlantısının geçici olarak kapalı olması ya da komisyon yapılandırması olabilir.

Boş liste geldiğinde ödeme oluşturmayın ve LydiaGate ile iletişime geçin. Yine de denerseniz ödeme nedene göre reddedilir. Ayrıntı: Ödeme Akışı.

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

Bu ucun döndürdüğü her installmentCount değeri, aynı terminal ve BIN ile ödeme oluştururken installment alanında kabul edilir. Oran da aynı kalır. Listede olmayan bir taksit sayısını gönderirseniz installment_not_allowed alırsınız. Terminalinizde o taksit sayısı tanımlı değilse hata ödeme oluşturma anında döner. Kartın markasına bağlı nedenlerde hata 3D Secure adımında ortaya çıkar. Kurtarma yolu: Ödeme Oluştur.

Liste karta özgüdür. Terminalinizin genel olarak izin verdiği bir taksit sayısı belirli bir kart için listede olmayabilir. Bu yüzden ödeme ekranınızdaki taksit menüsünü sabit yazmayın. Her kart için bu ucu çağırın ve dönen listeyi olduğu gibi gösterin.

Hız limiti

Hesap başına dakikalık bir hız limiti uygulanır. Ödeme ekranınızda her kart için çağrı yapmanız normaldir. Yine de kart numarası taramasına karşı bir tavan vardır. Aşımda 429 alırsınız. Yanıtta Retry-After başlığı varsa belirtilen süre kadar bekleyin. Başlık yoksa artan aralıklarla tekrar deneyin.

Olası hatalar

Kod	HTTP	Sebep
validation_error	400	bin tam 8 hane değil, terminalId eksik ya da baseAmount 1’den küçük.
terminal_not_allowed	403	Terminal size ait değil, pasif ya da kartın ailesi bu terminalde izinli değil.
rate_limited	429	Hız limiti aşıldı.

Tam liste: Hata Kodları.