Ödeme Geçidi Entegrasyon Diyagramı: Provizyon, 3-D Secure, Tahsilat ve Webhook'lar

Çoğu mimari diyagramında bir ödeme, mağazadan "Stripe"a ya da "Adyen"e giden tek bir oktur. Production'da ise bir taraflar zinciri ve iki zaman çizelgesidir: müşteri ödeme sayfasında beklerken olanlar ve dakikalar ya da günler sonra webhook ile gelenler. Ödeme hatalarının çoğu bu ikisinin arasındaki boşlukta yaşar.

Bu rehber, kartlı bir ödemeyi üye işyeri mühendisinin bakış açısından çiziyor: taraflar, mutlu yol, tarayıcıdaki sonucun neden doğruluk kaynağı olmadığı, provizyondan sonra neler olduğu ve paranın ve sipariş durumunun nerede değiştiğini gösteren bir diyagram. Sağlayıcıdan bağımsızdır; Stripe ve Adyen yalnızca ödeme hizmet sağlayıcılarının ayrıntıları nasıl belgelediğine örnek olarak geçiyor.

Taraflar

Mutlu yol

1. Müşteri Öde'yi seçer. Ön yüz, bir sipariş için ödemeyi başlatmasını backend'inizden ister.
2. Backend PSP'de bir ödeme oluşturur: tutar, para birimi, sipariş kimliği ve bir idempotency anahtarıyla; ardından PSP'nin istemci token'ını ön yüze iletir.
3. Ön yüz kart bilgilerini PSP'nin alanlarında toplar. Bunlar genellikle iframe'ler ya da bir SDK'dır; böylece kart numarası tarayıcıdan doğrudan PSP'ye gider ve sunucularınıza hiç dokunmaz.
4. 3-D Secure kararını kartı çıkaran banka verir. EMVCo iki akış tanımlar: sürtünmesiz akışta banka, müşteriye hiçbir şey sormadan bir risk değerlendirmesine göre onaylar; challenge akışında müşteri, örneğin tek kullanımlık bir kodla ya da bankacılık uygulamasıyla onay verir. Bazı bölgelerde güçlü müşteri doğrulaması bu şekilde karşılanır.
5. PSP provizyonu gönderir: acquirer ve kart ağı üzerinden kartı çıkaran bankaya; banka onaylar ve tutarı bloke eder.
6. Ön yüz sonucu gösterir. "Teşekkürler" demek sorun değil, ama gönderim yapmanın zamanı bu değil.
7. PSP bir webhook gönderir ve ödemenin provizyonunun alındığını bildirir. Backend'iniz bunu doğrular ve siparişi günceller.
8. Backend ödemeyi tahsil eder (capture): sipariş gönderildiğinde ya da dijital ürünlerde hemen.
9. PSP hakediş ödemesini yapar: toplu olarak ve komisyonlar düşülerek; bir mutabakat işi de ödemeleri siparişlerle eşleştirir.

Kart alanları uyumluluk açısından önemlidir. Bir e-ticaret sitesi yalnızca PSP'nin ödeme formunu sayfasına gömüyor ve kendisi hiçbir kart verisini saklamıyor, işlemiyor ya da iletmiyorsa, çok daha uzun SAQ A-EP yerine PCI DSS SAQ A'ya uygun olabilir. PCI Security Standards Council'in açıkladığı gibi, PCI DSS v4.0.1 kapsamında bu, sayfanın kötü amaçlı betiklere karşı korunmasını da gerektirir. Doğru anketi acquirer'ınızla teyit edin.

Tarayıcı neden doğruluk kaynağı değildir

Müşteri 3-D Secure sırasında sekmeyi kapatabilir, banka onay verdikten sonra bağlantısını kaybedebilir ya da yanlış anda sayfayı yenileyebilir. Sipariş durumunuz tarayıcının geri bildirmesine bağlıysa, ödenmiş bazı siparişler ödenmemiş görünür, başarısız bazıları da ödenmiş görünür. Doğruluk kaynağı PSP'nin webhook'ları ya da API'sidir. Onlara diğer mesaj akışlarına davrandığınız gibi davranın:

• İmzayı doğrulayın. PSP'ler webhook isteklerini imzalar; örneğin Stripe bir Stripe-Signature başlığıyla, Adyen ise HMAC imzalarıyla. Doğrulanamayan her şeyi reddedin.
• Hızlı yanıt verin, sonra işleyin. Stripe'ın webhook rehberi, karmaşık bir mantık çalıştırmadan önce 2xx yanıt dönülmesini ister. Doğrulanmış olayı bir kuyruğa koyun ve dönün.
• Tekrarlanan olayları bekleyin. Uç noktalar aynı olayı birden fazla kez alabilir. İşlenen olay kimliklerini kaydedin ve tekrarları atlayın.
• Sıraya güvenmeyin. Stripe, olayları oluşturuldukları sırayla teslim etmeyi garanti etmediğini belirtir. Mevcut duruma uymayan bir olay geldiğinde ödemeyi PSP'nin API'sinden çekin.
• Yeniden denemeleri bekleyin. Stripe, canlı modda başarısız teslimatları üstel geri çekilmeyle üç güne kadar yeniden dener; yani yavaş bir uç nokta aynı olayı sonra tekrar alır.

Aynı disiplin ters yönde de geçerlidir. Ödeme oluşturan ya da değiştiren her istekle bir idempotency anahtarı gönderin ve zaman aşımından sonra yeniden denerken aynı anahtarı kullanın; böylece bir yeniden deneme iki kez tahsilat yapamaz. Anahtarlar sonsuza kadar yaşamaz: Stripe onları 24 saat sonra silebilir, Adyen ise 7 ile 14 gün arasında saklar.

Provizyondan sonra: tahsilat, iadeler, ters ibrazlar ve hakediş ödemeleri

• Provizyon tutarı bloke eder; parayı tahsilat taşır. Tahsil etmezseniz provizyonun süresi dolar. Online kartlı ödemelerde bu süre genellikle bir hafta civarındadır; Stripe bunu kart markasına ve ödemeyi kimin başlattığına göre listeler. Süre dolmadan tahsil edin, yoksa bloke kalkar.
• Tahsilat yine de başarısız olabilir. Adyen, PSP kabul ettikten sonra kart şemasının bir tahsilatı reddettiği nadir durumları belgeler; bu yüzden sipariş durumlarınızın buna da bir yolu olmalı.
• İadeler, tahsil edilmiş bir ödeme üzerinde yeni işlemlerdir. Asenkron tamamlanır ve onlar da webhook olarak gelir.
• Ters ibrazlar (chargeback) kartı çıkaran bankadan gelir; bazen haftalar sonra, kart sahibi bir ödemeye itiraz ettiğinde. Bazı ağlar önce bir bilgi talebiyle başlar; yanıt verin, yoksa kazanması zor bir ters ibraza dönüşebilir.
• Hakediş ödemeleri mutabakat ister. PSP'nin hakediş ya da takas raporlarını kullanarak her hakediş ödemesini kapsadığı ödemeler, iadeler, komisyonlar ve ters ibrazlarla eşleştirin.

Diyagram

Nasıl okunur:

• Düz kenarlar ödemenin kendisidir: öde (1), ödemeyi başlat (2), ödemeyi oluştur (3), kart bilgilerini PSP'nin alanlarından PSP'ye gönder (4) ve PSP ile kart ağı arasında 3-D Secure ve provizyon (5).
• Kesikli kenarlar daha sonra olur: webhook (6), kuyruktaki doğrulanmış olay (7) ve siparişi güncelleyen ödeme API'si (8). Gece çalışan mutabakat işi PSP'nin hakediş raporlarını okur ve siparişlerle eşleştirir.
• Çerçeve üye işyerinin sistemlerini işaretler. İçine hiçbir ham kart verisi girmez; kart numarası PSP'nin alanlarından doğrudan PSP'ye gider.

Bir ödeme akışı nasıl çizilir

• Adımları numaralandırın. Ödemeler birer dizidir; numaralar, ayrı bir sekans diyagramına gerek kalmadan sırayı okunur kılar.
• Senkron olanı asenkrondan ayırın. Ödeme isteği için düz, webhook'lar, kuyruklar ve toplu işler için kesikli çizgi.
• Kart verisi sınırını işaretleyin. Hangi bileşenlerin kart numarasını görebildiğini gösterin. Barındırılan kart alanlarıyla sizinkilerin hiçbiri görmemeli.
• Sipariş durumunun nerede değiştiğini gösterin. Bunun tek bir sahibi olmalı ve tarayıcıyla değil, doğrulanmış olaylarla beslenmeli.
• Para işlemlerini adlandırın. Provizyon, tahsilat, iade ve hakediş ödemesi, zamanlamaları farklı olan farklı olaylardır; etiketleyin.
• Önemli hata durumlarını çizin: oluşturma sırasında zaman aşımı (aynı idempotency anahtarıyla yeniden deneyin), tekrarlanan webhook (tekilleştirin), yarıda bırakılan 3-D Secure doğrulaması (siparişin süresini doldurun), süresi dolmuş provizyon (yeniden provizyon alın ya da iptal edin).

Aynı akışın sekans görünümü için ödeme akışı diyagramı kullanım senaryosuna bakın. Olay tarafı için olay güdümlü mimari diyagramı rehberine, güvenlik incelemesi için de tehdit modelleme için veri akış diyagramlarına göz atın.

Archboard'da oluşturun

1. Google ya da GitHub ile giriş yapın ve bir diyagram oluşturun.
2. Müşteri için C4 Modeli paketinden bir Kişi, ödeme hizmet sağlayıcısı ile acquirer, kart ağı ve kartı çıkaran banka için de C4 Modeli paketinden iki Harici sistem düğümü ekleyin.
3. Üye işyeri sistemleri için Temel paketinden bir Çerçeve ekleyin ve içine C4 Modeli paketinden dört Konteyner düğümü koyun: ödeme web uygulaması, ödeme API'si, webhook işleyicisi ve mutabakat işi.
4. Çerçevenin içine siparişler ve ödemeler için Veri paketinden bir Postgres, ödeme olayları için de Veri paketinden bir Kuyruk ekleyin.
5. Kenarları sırayla numaralandırın; webhook, kuyruk ve mutabakat kenarlarını kesikli yapın ve çizgi stillerini açıklayan, Temel paketinden bir Markdown bloğu ekleyin.

Örnek 11 diyagram düğümü kullanıyor ve Free planın sınırları içinde kalıyor.

SSS

Ödeme geçidi ile ödeme işlemcisi arasındaki fark nedir? Ödeme geçidi, sistemlerinizin konuştuğu arayüzdür: API, kart alanları, webhook'lar. İşlemci ise işlemi kart ağları üzerinden taşır. Birçok PSP, bir acquiring ilişkisiyle birlikte ikisini de sunar.

Tarayıcı ödemenin başarılı olduğunu söylediğinde siparişi ödendi olarak işaretleyebilir miyim? Müşteriye bir onay gösterin, ama sipariş durumunu yalnızca doğrulanmış bir webhook'a ya da PSP'nin API'sine yapılan bir kontrole göre değiştirin.

Neden önce provizyon, sonra tahsilat? Yalnızca gönderilen ürün için ücret almak için. Provizyon tutarı garanti altına alır; tahsilat ise siparişi karşıladığınızda parayı taşır. Provizyonun süresinin dolmasına dikkat edin.

Sırası karışık gelen webhook'ları ele almam gerekir mi? Evet. İşleyiciyi idempotent yapın, siparişi imkânsız geçişleri reddeden bir durum makinesi olarak tutun ve emin olmadığınızda güncel ödemeyi PSP'den çekin.

Barındırılan kart alanlarını kullanmak beni PCI uyumlu yapar mı? Kapsamı daraltır; ortadan kaldırmaz. Yine de bir öz değerlendirme anketini doldurur ve ödeme sayfasını korursunuz. Hangisinin geçerli olduğunu acquirer'ınıza sorun.

Ücretsiz başlayın — tek kullanıcı, kredi kartı gerekmez.