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 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)

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

Üç 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 (çö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.

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), 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ı

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.