💳 Taksit ve BIN

Bir kart ile ödeme işlemi başlatılmadan önce, kartın BIN numarasına göre tip, marka ve geçerli taksit seçeneklerinin önceden sorgulanması gerekir. Bu endpoint, müşterinin girdiği kart bilgisine göre hangi taksitlerin sunulabileceğini belirtmek için kullanılır.

GET /api/cardPayment/installments

Kart bilgilerine göre geçerli taksit seçeneklerini döner.

---

🧾 Örnek Request

curl 'https://sandbox-pgw.klogs.io/api/cardPayment/installments?binNumber=415565&amount=1000&currency=TRY' \
  --header 'Authorization: Bearer API_KEY'

---

📥 Query Parametreleri

Parametre Adı	Konum	Tip	Zorunlu	Açıklama
binNumber	query	string	✅ Evet	Kart numarasının ilk 6 hanesi. Kartın ait olduğu banka, tipi ve markasını belirlemek için kullanılır.
amount	query	double	⛔ Hayır	İşlem tutarı. Girilirse, taksitli ödeme seçeneklerine göre tutar üzerinden hesaplama yapılabilir (örneğin, taksit başına ödeme).
currency	query	string	⛔ Hayır	Para birimi (örneğin: TRY, USD, EUR). Varsayılan TRY olabilir.

---

✅ HTTP 200 - Başarılı Yanıt

Sorgulanan BIN numarasına ve isteğe bağlı olarak tutara göre taksit seçenekleri döner. Her taksit seçeneğinde taksit sayısı, taksit başı ödeme, toplam ödeme gibi bilgiler olabilir.

Örnek JSON Yanıt:

{
  "cardBrand": "Visa",
  "cardType": "Credit",
  "bankName": "Garanti BBVA",
  "installments": [
    {
      "installmentCount": 1,
      "installmentAmount": 1000,
      "totalAmount": 1000
    },
    {
      "installmentCount": 3,
      "installmentAmount": 340,
      "totalAmount": 1020
    },
    {
      "installmentCount": 6,
      "installmentAmount": 175,
      "totalAmount": 1050
    }
  ]
}

---

⚠️ Notlar

• BIN (Bank Identification Number) kartın ilk 6 hanesidir ve kartın hangi bankaya, markaya (Visa, MasterCard, vs.) ve tipe (kredi/debit) ait olduğunu belirlemede kullanılır.
• Bu uç nokta, genellikle ödeme formunda kart numarası girildiğinde çalıştırılır ve kullanıcının görebileceği taksit seçeneklerini sağlar.
• amount parametresi girilmezse, yalnızca geçerli taksit seçenekleri listelenir; tutar hesaplaması yapılmaz.
• Taksit seçenekleri, sanal POS anlaşmalarına göre değişebilir. Her kart tipi/banka aynı sayıda taksit sunmayabilir.

---

🚧 Hatalar

HTTP Status Kodu	Anlamı	Açıklama
400	Bad Request	Gerekli parametre eksik veya hatalı (örneğin binNumber girilmemiş).
401	Unauthorized	Geçersiz veya eksik API anahtarı.
500	Internal Server Error	Sunucu taraflı beklenmeyen bir hata oluştu.

---

📘 Kullanım Senaryoları

🛒 1. Ödeme Formunda Kart Numarası Girildiğinde

Kullanıcı ödeme formuna kart numarasını girmeye başladığında, ilk 6 hane tamamlandığında installments endpoint'i çağrılarak, kullanılabilir taksit seçenekleri kullanıcıya gösterilir.

// Örnek frontend (pseudo-code)
if (cardNumber.length >== 6) {
  fetchInstallments(cardNumber);
}

---

💳 2. Kullanıcı Taksit Seçimi Yaptığında

Kullanıcı bir taksit seçeneğini seçtikten sonra, ödeme API'sine bu taksit sayısı ile devam edilir. Örneğin, installmentCount değeri ödeme isteğine eklenir.

{
  "cardNumber": "415565******1234",
  "installmentCount": 6,
  "amount": 1000
}

---

📱 3. Mobil Uygulamalarda

Mobil ödeme ekranlarında, kart numarası alanı girildikçe taksit seçenekleri arka planda dinamik olarak yüklenebilir ve kullanıcı seçimine sunulabilir.

---

🧠 Entegrasyon İpuçları

✅ 1. Giriş Doğrulama

• binNumber mutlaka 6 haneli olmalıdır. Daha az ya da fazla girilirse sorgulama yapılmamalıdır.
• Geliştiriciler istemci tarafında bu doğrulamayı yapmalıdır.

🧾 2. Taksit Hesaplamaları

• Eğer amount gönderilirse, installmentAmount ve totalAmount bilgileriyle birlikte döner. Bu sayede kullanıcı taksitli ödeme maliyetini önceden görebilir.
• Aksi takdirde sadece taksit sayıları listelenebilir.

🛡️ 3. Güvenlik

• API çağrıları mutlaka HTTPS üzerinden yapılmalı ve Authorization başlığı içinde geçerli Bearer Token kullanılmalıdır.
• API anahtarlarınızı istemci tarafında (özellikle tarayıcıda) asla açıkta bırakmayın.

🌐 4. Sandbox ve Production Ortamı

• https://sandbox-pgw.klogs.io sandbox ortamıdır. Gerçek işlemler için production URL’si kullanılmalıdır (örn. https://api-pgw.klogs.io).
• Sandbox ortamında test kartları ve sahte tutarlar ile entegrasyon testleri yapılabilir.

---

🎯 Önerilen UX

Kullanıcı deneyimini artırmak için:

• Kart numarası girilmeye başlanınca arka planda otomatik sorgulama yapılmalı.
• Sorgu başarılı olduğunda, taksit seçenekleri hemen gösterilmeli.
• Kullanıcı bir taksit seçeneği seçtiğinde toplam ödeme tutarı güncellenmeli.