Oturumlar

Bir CheckoutSession, alıcının etkileşim kurduğu şeydir — barındırılan checkout URL’sini barındıran TTL’li, tek kullanımlık bir nesnedir. Üç temel varlıktan en hafif olanıdır; ağır iş Orders ve Payment Intent’lerde (aşağıya bakınız) gerçekleşir.

Üç varlıklı veri modeli

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

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 ~24 karakter (18 rastgele bayt, base64url ile kodlanmış, padding yok). 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

Üç 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: Sunucu tarafında sert bir min/max uygulaması yoktur. Mantıklı değerler kullanın — 60 saniyenin altı, meşru alıcıların zaman aşımına uğrama riskini taşır; 7 günün üzeri, neredeyse kesinlikle terk edilmiş bir token üzerinde kapasite tutar. Alıcınızın beklenen karar penceresine uygun bir sayı seçin.
• Satıcı başına varsayılan: Panel üzerinden yapılandırılabilir, ancak yalnızca eski POST /b2b/v1/checkout-sessions (iki adımlı) yolu buna uyar. POST /b2b/v1/checkout-sessions/quick yolu, satıcı başına ayardan bağımsız olarak expires_in belirtilmezse her zaman 30 dakika olarak geri döner. Quick yolunda farklı bir varsayılana ihtiyacınız varsa, her çağrıda expires_in’i açıkça gönderin.
• Uygulama: Okumada tembel + periyodik bir cleanup worker. expires_at geçmiş bir oturum, durum alanı henüz yazılmamış olsa bile EXPIRED olarak değerlendirilir, bu yüzden tam süre dolma anında API üzerinden durumu okumaya 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 (bugün herkese açık bir resolve API’si yok; self-servis bir akış 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), zincir üstü tarayıcı 24 saat içinde fazla ödemeyi yakalar ve bir satıcı uyarısı yayar. Otomatik bir iade yoktur — iade API’si veya panel üzerinden manuel olarak verin.

Yanlış varlık ödemeleri

Depozito adresi (session, chain, asset) tuple başına oluşturulur. Bir alıcı adrese yanlış varlık gönderirse, zincir üstü eşleştirici onu tanımaz ve PaymentIntent, TTL süresi dolana kadar açık kalır. Fonları geri alabiliriz ama bu bir destek akışıdır, otomatik değil — alıcılara checkout sayfasında gösterilen tam varlığı göndermelerini söyleyin.

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). Müşterinizin doğal bir anahtarı yoksa, bunun için otomatik bir UUID oluşturun — SDK varsayılan olarak bunu yapar.

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), bu nedenle yeniden denenen bir /quick, siparişi tekrarlamadan alıcıya temiz bir oturum verir.

İki davranış Stripe stili bir idempotency katmanından farklıdır — dikkat edin:

• 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ı

Tam oluşturma istek gövdesi ve imzalama için Hızlı başlangıç sayfasına bakın.

Sırada ne var

• Kavramlar → Siparişler — Order varlığı (sipariş karşılama için gerçek kaynak olarak ele aldığınız varlık).
• Kavramlar → Zincirler ve varlıklar — desteklenen ağlar ve zincir başına kesinlik varsayımları.
• Webhook’lar → Genel bakış — her oturum durum geçişinde hangi event’ler tetiklenir.