Installment Payments (Taksit)

Installments (taksit) are a core part of card payments in Türkiye — cardholders routinely split a purchase into several monthly payments to their own bank. Kvell settles you the full amount upfront, minus commission; the split itself happens entirely between the cardholder and their issuing bank and never touches your ledger.

How it works#

1. You look up the plans eligible for the buyer's card (by BIN) and the purchase amount.
2. You show the picker — count and effective commission per option.
3. The buyer picks a plan.
4. You charge with that installment count.
5. Kvell settles you the full amount minus commission; the issuing bank collects the cardholder's monthly installments separately, on its own schedule.

1. Look up eligible plans#

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: <computed signature>"

{
  "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 is the first 6 digits of the card number — you get it back from tokenizing the card (POST /v1/cards/tokens responses include it) before you know anything else about it. amount is the purchase amount in kuruş; Kvell only returns plans the issuing bank actually allows for that BIN and amount — a small ticket or a debit card BIN may come back with only count: 1.

Real installment programs commonly go further than the example above — up to 9 or 12 taksit depending on the bank and card program. Always render the picker from the live eligiblePlans array Kvell returns for the current amount; never hardcode a list of counts, since eligibility varies by BIN, amount, and can change with bank promotions.

2. BIN metadata only (optional)#

If you just need the issuing bank, brand, and card type — before you know the purchase amount, e.g. to show a bank logo as the buyer types their card number — there's a standalone lookup:

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: <computed signature>"

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

3. Render the picker#

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' // single payment
          : `${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' });
}

The commission on an installment plan is charged to the cardholder, layered on top of the purchase price by their bank — it does not reduce what you receive. It's separate from the commission Kvell deducts from your settlement, covered next.

4. Commission math (worked example)#

A 1.200,00 TRY purchase (120000 kuruş) at 6 taksit, commissionRate: 0.065:

The buyer is charged the full 120000 — they don't see or pay the commission directly; it's deducted from your settlement. Their bank then splits their own 120000 into 6 monthly installments, entirely on the bank's side. GET /v1/payments/{id} reflects this same split on the payment record:

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

5. Charge with the chosen plan#

The two integration paths from Accepting Card Payments both support installments:

Hosted checkout — pass installmentEnabled: true when creating the session, and Kvell's hosted page looks up eligible plans and renders the picker for you. You don't need to call GET /v1/installments yourself in this path.

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: <computed signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "ORDER-2026-001",
    "amount": 120000,
    "currency": "TRY",
    "returnUrl": "https://merchant.example.com/return",
    "installmentEnabled": true
  }'

Direct API — call GET /v1/installments yourself, render your own picker, then pass the chosen installmentCount on the charge:

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: <computed signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "ORDER-2026-001",
    "amount": 120000,
    "currency": "TRY",
    "cardToken": "tok_9f8e7d6c5b4a",
    "installmentCount": 6
  }'

6. When a plan isn't eligible#

Kvell re-validates installmentCount against the card's eligible plans at charge time — bank programs and eligibility change (a promotional rate can expire between page load and checkout), so passing a count that's no longer eligible is rejected as a business-rule error, before the charge ever reaches the bank:

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

Treat GET /v1/installments as something to call right before checkout, not something to cache for the lifetime of a session — if this error comes back, re-fetch the eligible plans and re-prompt the buyer with the current list.

Next steps#