Neden Tahsilat (Capture) Kolay, Sonuçlandırma (Finalization) Zordur? (Odeme Capture Kolay Finalization Zordur)

Bir adım, altı adım

“Ödeme alındı” dediğinizde genellikle tek bir şeyi kastedersiniz: provider gateway, PSP'ye bir istek gönderdi ve PSP “parayı aldım” dedi. Bu, tek bir çağrı, tek bir cevap, tek bir doğrulamadır. Ama “sipariş tamamlandı” dediğinizde kastettiğiniz şey çok daha büyüktür: stok düşüldü, finans kaydı açıldı, sipariş onaylandı, müşteriye bildirim gitti, sepet temizlendi ve varsa sadakat puanı işlendi.

Capture:       Checkout Orchestrator → Provider Gateway → PSP → “alındı”

Finalization:  Stok düş  +  Finans kaydı  +  Sipariş onayı  +  Bildirim  +  Sepet temizliği
               (altı bağımsız adım, altısı da ayrı ayrı başarısız olabilir)

Bu bölüm, bu serinin en ayırt edici sorusunu ele alıyor: Capture neden kolay, finalization neden zordur?

Kavramlar ilk geçtiği yerde

📦 Capture
PSP'nin, önceden ayrılmış veya doğrudan istenmiş bir tutarı fiilen tahsil ettiğini bildirmesi; tek bir dış sistem gerçeğidir.

📦 Finalization
Capture'dan sonra işin gerçekten bitmesi için gereken tüm iç adımların toplamı: stok, finans, onay, bildirim, temizlik.

📦 Saga
Birden fazla adımı, her biri kendi başarısızlık ve telafi mantığıyla, uçtan uca yöneten bir iş akışı deseni.

📦 Telafi Adımı (Compensating Action)
Bir saga adımı geri alınamadığında, önceki adımların etkisini dengelemek için çalıştırılan ters işlem.

📦 Adım İşaretçisi (Step Marker)
Bir saga adımının tamamlandığını kalıcı olarak işaretleyen kayıt; yeniden çalıştığında adımın tekrarlanmasını önler.

Capture'ın kolaylığı, tek bir katılımcıya (PSP) ve tek bir cevaba bağlı olmasından gelir. Finalization'ın zorluğu, bağımsız başarısız olabilen çok sayıda katılımcıya bağlı olmasından gelir.

Capture neden basittir

Capture'ın başarı kriteri tek bir cümledir: PSP “tahsil ettim” dedi mi, demedi mi. Bu bilgi senkron bir cevapla veya webhook ile gelir, imzası doğrulanır, ilgili payment kaydı Captured durumuna geçer. Burada birden fazla veritabanına yazma, birden fazla servis çağırma, birbirine bağımlı sıralı adım yoktur — bir dış sistemin evet/hayır cevabı vardır.

Provider Gateway --istek--> PSP
Provider Gateway <--"captured"-- PSP
                        ↓
                Payment.Status = Captured
                (bir yazma, bir karar)

Finalization neden bir saga'dır

Capture bittiğinde iş bitmemiştir; asıl karmaşık kısım şimdi başlar. Siparişin “gerçekten bitmiş” sayılması için aşağıdaki adımların hepsinin, herhangi bir sırada ama hepsi tamamlanana kadar, güvenilir şekilde yürümesi gerekir:

Finalization Saga
  1. Stok Servisi'nde rezervasyonu kesin düşüşe çevir
  2. Finans/Ledger'da gelir kaydını aç
  3. Sipariş satırlarını “onaylandı” olarak işaretle
  4. Müşteriye bildirim gönder
  5. Sepeti/aktif intent'i temizle
  6. (Varsa) sadakat puanı veya kampanya etkisini işle

Bu altı adımın her biri kendi hata modeline sahiptir: stok servisi geçici olarak erişilemez olabilir, finans servisi bir doğrulama hatası verebilir, bildirim servisi zaman aşımına uğrayabilir. Capture'da tek bir “evet/hayır” vardı; burada altı bağımsız “evet/hayır” vardır ve bunların hiçbiri diğerini garanti etmez.

Kısmi finalization: en tehlikeli ara durum

En zor senaryo, saga'nın yarısının çalışıp yarısının çalışmadığı durumdur. Örneğin stok düşürüldü ama finans kaydı açılamadı; sistem crash oldu ve worker yeniden başladığında hangi adımların tamamlandığını bilmesi gerekir.

Finalization saga çalışıyor
  ✓ Stok düşüldü
  ✓ Sipariş onaylandı
  ✗ Finans kaydı — worker crash oldu
  ? Bildirim — henüz denenmedi

Worker yeniden başlar: Hangi adımları TEKRAR çalıştırmalı, hangilerini ATLAMALI?

Bu soruyu adım işaretçileri (step markers) olmadan cevaplayamazsınız. Her adım, kendi tamamlanma durumunu kalıcı olarak kaydetmelidir; aksi halde worker yeniden başladığında ya tüm saga'yı baştan çalıştırıp stok'u iki kez düşürür, ya da hiçbir şey yapmayıp sipariş sonsuza dek yarım kalır.

Neden bu ayrım hafife alınır

Çoğu ekip “ödeme entegrasyonu” dediğinde yalnızca capture'ı kasteder ve bunu bir haftalık iş olarak planlar. Finalization saga'sı ise genellikle “detaylar” olarak görülür ve yeterince tasarlanmadan production'a çıkar. Gerçekte capture, bu serinin ilk iki bölümünde gösterdiğimiz gibi tek bir dış sistemle konuşmaktır; finalization ise sizin kendi sisteminizin, kendi hatalarına karşı dayanıklı olmasını gerektirir. İkincisi çok daha büyük bir mühendislik yatırımı ister.

Bu bölümde en çok karışan eşleştirmeler

❌ Ödeme entegrasyonu = Capture'ı çalıştırmak
✓ Ödeme entegrasyonu = Capture + finalization saga'sının tamamı

❌ Capture başarılı olduysa iş bitmiştir
✓ Capture, finalization saga'sının başlangıç tetikleyicisidir, bitişi değil

❌ Saga adımlarının sırası önemli değildir, hepsi “aynı işlem”dir
✓ Her adım bağımsız başarısız olabilir; her birinin kendi retry ve telafi mantığı gerekir

❌ Worker crash olursa saga'yı baştan çalıştırmak güvenlidir
✓ Adım işaretçisi olmadan baştan çalıştırmak, tamamlanmış adımları tekrarlayıp yan etki üretir

Finalization saga'nızı test etme listesi

1. Finalization saga'nızdaki adımları tek tek yazın: kaç adım var, hangileri bağımsız servislere gidiyor?
2. Her adımın kendi başına idempotent olup olmadığını test edin: aynı adımı iki kez çalıştırırsanız sonuç değişiyor mu?
3. Saga'nın ortasında worker'ı kasten öldürün (chaos test). Yeniden başladığında hangi adımları atlıyor, hangilerini tekrarlıyor?
4. Her adımın başarısız olma senaryosu için bir telafi veya retry planı var mı, yoksa “bu adım hep başarılı olur” varsayımıyla mı yazıldı?
5. Capture başarılı ama finalization saga'sı hiç başlamamışsa, bunu kaç dakika içinde fark ediyorsunuz?

Bu beş testten ikisini geçemiyorsanız, finalization saga'nız muhtemelen “mutlu yol” için yazılmış, hata yolu için değil.

Bu bölümden aklında kalması gerekenler

1. Capture, tek bir dış sistemin (PSP) evet/hayır cevabıdır; basitliği buradan gelir.
2. Finalization, birden fazla bağımsız adımın hepsinin tamamlanmasını gerektiren bir saga'dır; zorluğu buradan gelir.
3. Kısmi finalization (bazı adımlar tamam, bazıları değil) en tehlikeli ara durumdur ve adım işaretçileri olmadan güvenli şekilde kurtarılamaz.
4. “Ödeme entegrasyonu” yalnızca capture'ı kapsıyorsa, projenin en riskli kısmı planın dışında kalmıştır.

Capture, PSP'nin sizinle anlaştığı andır. Finalization, sizin kendi sisteminizle anlaştığınız andır — ve genellikle daha zor olan taraf budur.