> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payven.com.tr/llms.txt
> Use this file to discover all available pages before exploring further.

# Taksit

> Kart programlarına göre taksitli ödeme alma.

Taksitli ödeme, müşterinin tutarı **eşit aylık taksitler halinde** ödediği akıştır. Hangi taksitlerin uygulanabileceği üç parametreye bağlıdır:

1. **Banka kart programı** (Bonus, Maximum, Axess, World, Paraf, Cardfinans, vb.)
2. **Organizasyonunuzun banka anlaşması** (her banka kendi taksit kampanyalarını tanımlar)
3. **Ödeme tutarı** (her bankanın taksit başına minimum tutarı vardır)

## İstekte taksit alanı

`CreatePaymentRequest` ve `Init3DRequest` body'lerinde `installment` alanı taksit sayısını taşır:

```json theme={null}
{
  "amount":         { "amount": 60000, "currency": "TRY" },
  "installment":    6,
  "operation_type": "sale",
  "card":           { ... }
}
```

| Değer    | Anlam               |
| -------- | ------------------- |
| `1`      | Peşin (varsayılan)  |
| `2`–`12` | Aylık taksit sayısı |

Banka taksiti destekliyorsa onaylar; desteklemiyorsa `422 invalid_installment` hatası döner.

## Müşteriye uygun seçenekleri sunma

Müşteri kart numarasını yazdığında, BIN'e göre uygun taksit seçeneklerini göstermek istiyorsunuz. İki yaklaşım:

<Tabs>
  <Tab title="Hosted Checkout (kolay)">
    [Hosted Checkout](/sanal-pos/payments/hosted-checkout) sayfası taksit seçeneklerini **otomatik** doldurur — kart programı, BIN ve banka anlaşması bazlı tüm sınırları Payven yönetir.

    Sadece üst sınır koymak isterseniz `allowed_installments` ile filtreleyin:

    ```json theme={null}
    {
      "amount":               { "amount": 60000, "currency": "TRY" },
      "allowed_installments": [1, 3, 6, 9]
    }
    ```
  </Tab>

  <Tab title="Direct API">
    Kart numarasının ilk 6 hanesini alıp BIN'i çözümleyebilirsiniz:

    ```bash theme={null}
    curl https://identity.payven.com.tr/api/v1/lookups/bank-bins/resolve?prefix=454671 \
      -H "Authorization: Bearer $PAYVEN_TOKEN"
    ```

    Yanıt; bankayı, kart programını ve kart tipini (`credit/debit/prepaid`) verir. Taksit kampanyaları ise konsoldan tanımlanan **organizasyon anlaşma tablosundan** çekilir — yakında public bir `/installments` endpoint'i ile dinamik sorgulanabilir hale gelecektir.

    Mevcut durumda sabit kampanya tablonuzu istemcinize gömerek BIN'e göre filtreleyebilirsiniz.
  </Tab>
</Tabs>

## Yanıttaki taksit bilgisi

`PaymentStatus` (sorgulama) yanıtında işlem yapılırken kullanılan taksit sayısı bulunur:

```json theme={null}
{
  "transaction_id": "...",
  "amount":         60000,
  "currency":       "TRY",
  "is_3d_secure":   true,
  "extra_properties": {
    "auth_code":               "123456",
    "host_reference":          "PAYVEN-REF-789",
    "provider_transaction_id": "9f3d2b8e-..."
  }
}
```

Taksit sayısı request'te belirttiğiniz değerdir; banka onayında `extra_properties.installment` da olabilir (konnektöre göre değişir).

## Taksit kuralları

<Check>**Borç/prepaid kartında taksit yok.** Bu kartlarda `installment > 1` `422 invalid_installment` ile reddedilir.</Check>
<Check>**Yabancı kartta taksit yok.** Yurt dışı bankalarının kartları taksite uygun değildir.</Check>
<Check>**Minimum tutar.** Her bankanın taksit başına minimum tutar şartı vardır (genelde 100 ₺).</Check>
<Check>**Maximum taksit.** Bankaya göre değişir. Yaygın üst sınır 12 ay; bazı kampanyalarda 18-24 ay.</Check>
<Check>**Komisyon kart programına bağlı.** Her banka kendi taksit kampanyasını tanımlar — organizasyon anlaşmanıza yansır.</Check>

## Hata response'ları

| HTTP  | `code`                | Anlam                                                                                                                  |
| ----- | --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `422` | `invalid_installment` | Taksit sayısı bu kart için desteklenmiyor (debit/prepaid/yurtdışı kart, tutar minimumu altında, banka destek vermiyor) |
| `422` | `bank_declined`       | Banka taksit talebini reddetti (anlaşma dışı)                                                                          |

Hata yanıtı RFC 9457 problem+json formatındadır.

## Yol haritası

* **Public installment lookup endpoint** — BIN + tutar kombinasyonu için izin verilen taksit listesini canlı sorgulama
* **Kampanya editor UI** — banka kampanyalarını konsoldan kural motoruna eklemek

Güncellemeler için: [Changelog](/resources/changelog).