Taksitli Ödemeler

Taksit, Türkiye'deki kart ödemelerinin temel bir parçasıdır — kart sahipleri bir alışverişi kendi bankalarına birkaç aylık ödemeye bölmeyi rutin olarak tercih eder. Kvell size tam tutarı, komisyon düşülmüş şekilde peşin öder; bölünmenin kendisi tamamen kart sahibi ile kartı veren banka arasında gerçekleşir ve hiçbir zaman sizin ledger'ınıza dokunmaz.

Nasıl çalışır#

1. Alıcının kartı için (BIN üzerinden) ve satın alma tutarı için uygun planları sorgularsınız.
2. Seçiciyi gösterirsiniz — her seçenek için taksit sayısı ve geçerli komisyon.
3. Alıcı bir plan seçer.
4. O taksit sayısıyla tahsilatı gerçekleştirirsiniz.
5. Kvell size tam tutarı komisyon düşülmüş olarak öder; kartı veren banka, kart sahibinin aylık taksitlerini kendi takvimine göre ayrıca tahsil eder.

1. Uygun planları sorgulayın#

curl "https://api.pay.kvell.group/v1/installments?bin=415565&amount=15000" \
  -H "X-Api-Key: pk_live_a1b2c3d4e5f6g7h8" \
  -H "X-Timestamp: 2026-04-13T10:00:00Z" \
  -H "X-Signature: <hesaplanan imza>"

{
  "bin": "415565",
  "bank": "Garanti BBVA",
  "brand": "visa",
  "cardType": "credit",
  "country": "TR",
  "eligiblePlans": [
    { "count": 1, "commissionRate": 0.019 },
    { "count": 3, "commissionRate": 0.035 },
    { "count": 6, "commissionRate": 0.065 }
  ]
}

bin, kart numarasının ilk 6 hanesidir — kartın başka hiçbir bilgisini bilmeden önce, kartı tokenize ettiğinizde (POST /v1/cards/tokens yanıtları bunu içerir) geri alırsınız. amount, kuruş cinsinden satın alma tutarıdır; Kvell yalnızca kartı veren bankanın o BIN ve tutar için gerçekten izin verdiği planları döndürür — küçük bir tutar veya bir banka kartı (debit) BIN'i yalnızca count: 1 ile dönebilir.

Gerçek taksit programları yukarıdaki örnekten daha da ileri gidebilir — bankaya ve kart programına bağlı olarak 9 veya 12 taksite kadar. Seçiciyi her zaman Kvell'in o an döndürdüğü canlı eligiblePlans dizisinden oluşturun; asla sabit bir taksit sayısı listesi kodlamayın, çünkü uygunluk BIN'e, tutara göre değişir ve banka kampanyalarıyla değişebilir.

2. Yalnızca BIN meta verisi (isteğe bağlı)#

Yalnızca kartı veren banka, marka ve kart tipine ihtiyacınız varsa — satın alma tutarını bilmeden önce, örneğin alıcı kart numarasını yazarken bir banka logosu göstermek için — bağımsız bir sorgulama mevcuttur:

curl "https://api.pay.kvell.group/v1/bins/415565" \
  -H "X-Api-Key: pk_live_a1b2c3d4e5f6g7h8" \
  -H "X-Timestamp: 2026-04-13T10:00:00Z" \
  -H "X-Signature: <hesaplanan imza>"

{
  "bin": "415565",
  "bank": "Garanti BBVA",
  "brand": "visa",
  "cardType": "credit",
  "country": "TR"
}

3. Seçiciyi oluşturun#

interface Plan {
  count: number;
  commissionRate: number;
}

function renderPlans(amountMinor: number, plans: Plan[]) {
  return plans.map((plan) => {
    const commission = Math.round(amountMinor * plan.commissionRate);
    const totalMinor = amountMinor + commission;
    const perMonthMinor = Math.round(totalMinor / plan.count);
    return {
      count: plan.count,
      label:
        plan.count === 1
          ? 'Tek çekim'
          : `${plan.count}x ${formatTRY(perMonthMinor)}/ay`, // "6x 132,00 ₺/ay"
      totalLabel: formatTRY(totalMinor),
    };
  });
}

function formatTRY(minor: number): string {
  return (minor / 100).toLocaleString('tr-TR', { style: 'currency', currency: 'TRY' });
}

Bir taksit planındaki komisyon, kart sahibine faturalandırılır ve kendi bankası tarafından satın alma fiyatının üzerine eklenir — sizin aldığınız tutarı azaltmaz. Bu, Kvell'in yerleşimden düştüğü komisyondan ayrıdır; ona sırada geliyoruz.

4. Komisyon hesabı (örnek üzerinden)#

1.200,00 TL'lik bir satın alma (120000 kuruş), 6 taksit ve commissionRate: 0.065 ile:

Alıcıya tam 120000 tutarı tahsil edilir — komisyonu doğrudan görmez veya ödemez; bu sizin yerleşiminizden düşülür. Bankası daha sonra kendi 120000 tutarını 6 aylık taksite böler; bu tamamen banka tarafında gerçekleşir. GET /v1/payments/{id}, aynı bölünmeyi ödeme kaydında yansıtır:

{
  "amount": 120000,
  "commission": 7800,
  "netAmount": 112200,
  "installmentCount": 6
}

5. Seçilen planla tahsilat yapın#

Kart Ödemelerini Kabul Etme rehberindeki her iki entegrasyon yolu da taksitleri destekler:

Barındırılan checkout — oturumu oluştururken installmentEnabled: true gönderin, Kvell'in barındırılan sayfası uygun planları sorgular ve seçiciyi sizin için oluşturur. Bu yolda GET /v1/installments'ı kendiniz çağırmanıza gerek yoktur.

curl -X POST https://api.pay.kvell.group/v1/payments/sessions \
  -H "X-Api-Key: pk_live_a1b2c3d4e5f6g7h8" \
  -H "X-Timestamp: 2026-04-13T10:00:00Z" \
  -H "X-Signature: <hesaplanan imza>" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "ORDER-2026-001",
    "amount": 120000,
    "currency": "TRY",
    "returnUrl": "https://merchant.example.com/return",
    "installmentEnabled": true
  }'

Doğrudan API — GET /v1/installments'ı kendiniz çağırın, kendi seçicinizi oluşturun, ardından seçilen installmentCount'u tahsilatta gönderin:

curl -X POST https://api.pay.kvell.group/v1/payments/card \
  -H "X-Api-Key: pk_live_a1b2c3d4e5f6g7h8" \
  -H "X-Timestamp: 2026-04-13T10:00:00Z" \
  -H "X-Signature: <hesaplanan imza>" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "ORDER-2026-001",
    "amount": 120000,
    "currency": "TRY",
    "cardToken": "tok_9f8e7d6c5b4a",
    "installmentCount": 6
  }'

6. Bir plan uygun olmadığında#

Kvell, tahsilat anında installmentCount'u kartın uygun planlarına karşı yeniden doğrular — banka programları ve uygunluk değişir (bir promosyon oranı sayfa yüklenmesi ile checkout arasında sona erebilir), bu yüzden artık uygun olmayan bir sayı göndermek, tahsilat bankaya hiç ulaşmadan bir iş kuralı hatası olarak reddedilir:

{
  "code": "KVELL-PAY-4030",
  "message": "installmentCount is not eligible for this card and amount.",
  "requestId": "7b9e5c21-4a3f-4e8a-b9d2-1f4a8c9e5b10"
}

GET /v1/installments'ı, bir oturumun ömrü boyunca önbelleğe alınacak bir şey olarak değil, checkout'tan hemen önce çağırılacak bir şey olarak ele alın — bu hata dönerse, uygun planları yeniden sorgulayın ve alıcıyı güncel liste ile tekrar yönlendirin.

Sonraki adımlar#