<!-- Source: https://docs.infraio.xyz/tr/concepts/sessions -->
<!-- Last updated: 2026-10-04 -->

# Oturumlar

Bir **CheckoutSession**, alıcının etkileşim kurduğu şeydir: barındırılan
checkout URL'sini barındıran, süre sınırlı, tek kullanımlık bir nesnedir.
Üç temel varlıktan en hafif olanıdır. Mantığınızın çoğu
[Orders](https://docs.infraio.xyz/tr/concepts/orders) ve **Payment Intent**'lerle (aşağıya bakınız)
çalışır.

## Üç varlıklı veri modeli

```
CheckoutSession  ←  1:1  →  Order  ←  1:N  →  PaymentIntent
   (alıcı)                  (katalog)        (her ödeme denemesi)
```

| Varlık | Amaç | Ömür |
| --- | --- | --- |
| **CheckoutSession** | Alıcıya yönelik — `session_key`, `checkout_url`, TTL içerir | Dakikalar (varsayılan 30) |
| **Order** | Katalog durumunuz — line item'lar, toplamlar, iadeler | Kalıcı kayıt |
| **PaymentIntent** | Bir zincir/varlık üzerinde bir ödeme denemesi | Saatler; tahsil edilir veya süresi dolar |

Bir oturum ve siparişi birlikte oluşturursunuz (`POST /b2b/v1/checkout-sessions/quick`
aracılığıyla). Alıcı checkout sayfasında her varlık seçtiğinde, doğru zincire
karşı yeni bir PaymentIntent açılır. Checkout sırasında varlık değiştirirlerse,
önceki intent `EXPIRED` durumuna geçer ve yenisi başlar.

## Tanımlayıcı

Bir oturum `session_key`'i ile tanımlanır:

```
cst_G-SO92J7HNWkwMHEHjD4oO1Z
```

URL güvenli, önekten sonra yaklaşık 24 karakter. Barındırılan checkout sayfası
`https://checkout.infraio.xyz/<session_key>` adresindedir — oturum
anahtarını, o tek checkout için bir bearer kimlik bilgisi olarak değerlendirin.

## Yaşam döngüsü — CheckoutSession

```mermaid
stateDiagram-v2
    [*] --> ACTIVE
    ACTIVE --> COMPLETED: a PaymentIntent settles
    ACTIVE --> EXPIRED:   expires_at elapsed
    ACTIVE --> CANCELED:  buyer or merchant cancels
    COMPLETED --> [*]
    EXPIRED --> [*]
    CANCELED --> [*]
```

| Durum | Anlamı |
| --- | --- |
| `ACTIVE` | Oturum oluşturuldu ve açık. Checkout URL'si kullanılabilir. |
| `COMPLETED` | Bu oturumdaki bir PaymentIntent tahsil edildi. Order artık `PAID` (veya eksik ödendiyse `PARTIAL_PAID`). |
| `EXPIRED` | `expires_at` tahsil edilmeden geçti. Açık Order'lar iptal edilir. |
| `CANCELED` | Açık iptal — ya alıcı "iptal" butonuna bastı ya da siz iptal uç noktasını çağırdınız. |

Üç son durum karşılıklı olarak özel ve nihaidir. Yeniden denemek isterseniz
(örn. eksik ödeme sonrası) aynı Order'a karşı yeni bir CheckoutSession
oluşturulabilir.

## TTL

- **Varsayılan:** 30 dakika (oluşturma sırasında `expires_in` alanı ile
  saniye cinsinden yapılandırılabilir).
- **Sınırlar:** Uygulanan bir minimum veya maksimum yoktur. Alıcınızın
  beklenen karar penceresine uygun bir değer seçin: 60 saniyenin altı
  meşru alıcıların zaman aşımına uğrama riskini taşır ve 7 günden uzun
  açık kalan bir oturum neredeyse kesinlikle terk edilmiştir.
- **Satıcı başına varsayılan:** Panelden bir varsayılan ayarlayabilirsiniz,
  ancak yalnızca `POST /b2b/v1/checkout-sessions` (iki adımlı) buna uyar.
  `POST /b2b/v1/checkout-sessions/quick`, panel ayarından bağımsız olarak
  `expires_in` belirtilmezse **30 dakika** kullanır. `/quick` ile farklı bir
  varsayılan kullanmak için her çağrıda `expires_in` gönderin.
- **Uygulama:** `expires_at` geçmiş bir oturum, durumu henüz güncellenmemiş
  olsa bile `EXPIRED` olarak değerlendirilir, bu yüzden tam süre dolma
  anında durum değerine güvenmeyin.

## Eksik ödeme

Bir alıcı oturum tutarından daha az gönderirse, PaymentIntent yine de kısmi
tutar için tahsil edilir ve Order `PARTIAL_PAID` durumuna geçer.
CheckoutSession `COMPLETED` durumuna geçer (bir PaymentIntent tahsil edildi),
dolayısıyla artık yeniden kullanılabilir değildir.

Eksikliği tam ödeme olarak kabul etmek için, sipariş `PAID` durumuna
çözümlenebilir. Bkz. [Kavramlar → Siparişler](https://docs.infraio.xyz/tr/concepts/orders)
(çözümleme API üzerinden kullanılamaz; self-servis kalmak için bunun yerine
kalanı tahsil edin). Kalanı tahsil etmek için aynı Order'a karşı kalan
tutarda **yeni** bir CheckoutSession oluşturun.

## Fazla ödeme

Alıcı oturum tutarından daha fazla gönderirse (nadir, ama manuel
transferlerde olur), InfraIO Pay fazla ödemeyi 24 saat içinde tespit eder ve
sizi bilgilendirir. Otomatik olarak iade edilmez. İadeyi iade API'si veya
panel üzerinden verin.

## Yanlış varlık ödemeleri

Depozito adresi tek bir oturum, ağ ve varlık için oluşturulur. Bir alıcı
adrese farklı bir varlık gönderirse ödeme eşleştirilmez ve PaymentIntent,
oturum süresi dolana kadar açık kalır. Destek ekibi fonları geri almanıza
yardımcı olabilir, ancak bu otomatik değildir. Alıcılara checkout sayfasında
gösterilen tam varlığı göndermelerini söyleyin.

TRON, Solana ve TON'da depozito adresi yoktur, bu yüzden bu yalnızca EVM ağları için geçerlidir: alıcı doğrudan sizin cüzdanınıza öder. Bkz. [Doğrudan cüzdana ödeme yapan ağlar](https://docs.infraio.xyz/tr/concepts/chains#doğrudan-cüzdana-ödeme-yapan-ağlar).

## Oluşturmada idempotency

`POST /b2b/v1/checkout-sessions/quick` istek gövdesinde bir
`idempotency_key` alanı kabul eder (not: **gövde alanı, HTTP başlığı
değil**). Doğal bir anahtarınız yoksa bir UUID oluşturun.

Anahtar **Order**'ı tekrar etmeyi engeller, CheckoutSession'ı değil. Aynı
anahtarla yeniden denemede, `/quick` *orijinal siparişi* döndürür
(`order_id` stabildir) ancak **yeni bir CheckoutSession** üretir — her
seferinde yeni bir `session_key` ve `checkout_url`. Bu kasıtlıdır: bir
Order birden fazla checkout denemesini destekleyebilir (bkz.
[Siparişler](https://docs.infraio.xyz/tr/concepts/orders)), bu nedenle yeniden denenen bir `/quick`,
siparişi tekrarlamadan alıcıya temiz bir oturum verir.

Dikkat etmeniz gereken iki davranış:

- **Gövde hash'lenmez veya karşılaştırılmaz.** Bir anahtarı *farklı* bir
  gövde ile yeniden kullanmak `409` döndürmez — sunucu, o anahtarın altında
  zaten saklanan siparişi sessizce döndürür ve yeni gövdeyi yok sayar. Bu
  yüzden bir `idempotency_key`'i tek bir mantıksal sipariş için tek atışlık
  bir token olarak değerlendirin; farklı sepetler arasında asla yeniden
  kullanmayın.
- **Yalnızca Order tekrar etmez, oturum değil.** *Aynı* checkout URL'sini
  geri istiyorsanız, ilk yanıttan `session_key` / `checkout_url`'yi
  saklayın — `/quick`'i yeniden çağırmak eskisini döndürmez. Bir siparişe
  karşı üretilen her oturumu listelemek için
  `GET /b2b/v1/checkout-sessions/by-order/:order_id` kullanın.

## API uç noktaları

| Method | Path | Notlar |
| --- | --- | --- |
| `POST` | `/b2b/v1/checkout-sessions/quick` | Tek çağrıda sipariş + oturum oluştur |
| `POST` | `/b2b/v1/checkout-sessions` | Mevcut bir siparişe karşı oturum oluştur |
| `GET` | `/b2b/v1/checkout-sessions/by-order/:order_id` | Bir sipariş için tüm oturumları listele (yeniden deneme geçmişi için) |

Tam oluşturma istek gövdesi ve imzalama için
[Hızlı başlangıç](https://docs.infraio.xyz/tr/get-started/quickstart) sayfasına bakın.

## Sırada ne var

- [Kavramlar → Siparişler](https://docs.infraio.xyz/tr/concepts/orders) — Order varlığı (sipariş
  karşılama için gerçek kaynak olarak ele aldığınız varlık).
- [Kavramlar → Zincirler ve varlıklar](https://docs.infraio.xyz/tr/concepts/chains) — desteklenen
  ağlar ve zincir başına kesinlik varsayımları.
- [Webhook'lar → Genel bakış](https://docs.infraio.xyz/tr/webhooks/overview) — her oturum durum
  geçişinde hangi event'ler tetiklenir.