Ödeme Entegrasyon Mimarisi: Kartlar, Cüzdanlar, Faturalar ve Sipariş Durumu

Ödeme entegrasyonu, nadiren tek bir SDK eklemek kadar basittir. DigiForge'daki yapılarımızda, ekiplerin birden fazla ödeme yöntemini (kartlar, dijital cüzdanlar, faturalı ödemeler) ele almanın karmaşıklığını ve ardından bunları bir sipariş yaşam döngüsüne bağlamayı hafife alması nedeniyle projelerin şiştiğini gördük. Her ödeme türünün kendine özgü tuhaflıkları vardır ve bunları tutarlı bir mimari olmadan birbirine dikmek, kırılgan kod ve acı verici mutabakata yol açar. Bu makale, birleşik bir ödeme entegrasyon katmanının nasıl göründüğünü, hem yerleşik kalıplardan hem de stablecoin destekli kartlar gibi daha yeni gelişmelerden yararlanarak ayrıştırıyor.

Kartlar: Tokenizasyon, Ağ Tokenları ve Stablecoin Destekli Kartların Yükselişi

Kart ödemeleri, e-ticaretin ve birçok SaaS işletmesinin bel kemiği olmaya devam ediyor. Altın kural, ham kart numaralarını asla işlememektir. PCI uyumlu bir ağ geçidi (Stripe, Braintree, Adyen) aracılığıyla tokenizasyon olmazsa olmazdır. Ancak daha ince bir katman daha var: ağ tokenları. Bunlar, kart ağlarının kendileri tarafından verilen, cihaza özel, tek kullanımlık tokenlardır ve daha iyi yetkilendirme oranları ve azaltılmış dolandırıcılık sunar. Müşterilerimizi, özellikle yinelenen ödemeler işliyorlarsa, ağ tokenizasyonunu erken benimsemeye iteriz çünkü token ömürleri daha uzundur ve güncellemeler ağ tarafından yapılır.

Daha yeni bir dalga ise stablecoin destekli kart. 2025'in sonları itibarıyla, kripto kart hacmi yıllık 18 milyar dolarlık bir ciroya ulaştı ve 2023'ten bu yana yıllık %106 büyüyor (Wirex/Crossmint basın açıklaması). Buradaki mimari farklıdır: bir banka hesabından veya kredi limitinden çekmek yerine, kart bir stablecoin cüzdanından çeker. Geliştiriciler için bu, bir cüzdan sağlayıcısı (Crossmint'in akıllı cüzdanı gibi) ve bir kart ihraççısı (Wirex gibi) ile entegrasyon anlamına gelir. Zorluk uyumluluktur - basın açıklaması, fintech'lerin daha önce cüzdan, ihraççı ve uyumluluk çerçevelerini ayrı ayrı bir araya getirmek zorunda kaldığını belirtiyor. DigiForge'da benzer çok satıcılı entegrasyonlar üzerinde çalıştık ve birleşik bir işlem modeline sahip bir soyutlama katmanının gerekli olduğunu gördük. Aksi takdirde, başarısız bir ödemede hata ayıklamak, üç sağlayıcı panosunda bir kovalamacaya dönüşür.

Dijital Cüzdanlar: UPI, Google Pay ve Barındırılan ile API Tabanlı Entegrasyon

Dijital cüzdanlar tek bir yapıda değildir. Google Pay (artık daha geniş Google Payments ekosisteminin bir parçası) Hindistan'ın Paytm gibi UPI tabanlı cüzdanlarından farklı çalışır ve her ikisi de uygulamaya özel cüzdanlardan farklıdır. Mimari karar, barındırılan bir ödeme sayfası (daha basit, daha az kontrol) ile API odaklı bir entegrasyon (daha karmaşık, daha zengin kullanıcı deneyimi) arasında yapılır.

Google Pay, Apple Pay ve PayPal gibi cüzdanlar için yaygın desen, bir sayfa veya yönlendirme tetikleyen bir cüzdan butonudur. Entegrasyon genellikle ödeme geçidinin birleşik ödeme sayfası üzerinden yapılır — örneğin Stripe'ın Payment Element'i tüm cüzdanları otomatik olarak işler. Bu birçok durum için yeterlidir, ancak özel stil gerektiğinde veya ödeme öncesinde ek veri toplamak istediğimizde sınırlamalarla karşılaştık. Cüzdanın kendi SDK'sı ile daha derin bir entegrasyon daha fazla kontrol sağlar ancak ayrı kod yollarını sürdürmeyi taahhüt eder.

Paytm gibi UPI tabanlı cüzdanlar farklı çalışır. UPI (Birleşik Ödeme Arayüzü), doğrudan bankalar arası transferlere izin veren anlık bir ödeme sistemidir. Paytm'i bir ödeme yöntemi olarak entegre ederken tipik akış şöyledir: kullanıcı Paytm'i seçer, arka uç bir ödeme talebi oluşturur, kullanıcı Paytm uygulamasında yetki verir ve Paytm bir geri çağırma gönderir. Buradaki zorluk, tekrarsızlıktır — UPI ödemeleri banka tarafında başarılı olabilir ancak ağ zaman aşımları nedeniyle satıcıya başarısızlık bildirebilir. Sipariş durumumuzu Paytm'in işlem durumuyla birkaç dakikada bir karşılaştıran bir mutabakat işi oluşturuyoruz.

Faturalar: Ödeme Talepleri ve Mutabakat

Faturalı ödemeler — işletmenin bir fatura oluşturup müşterinin daha sonra ödeme yaptığı durumlar — farklı bir dizi sorunu beraberinde getirir. IRS Ödemeler sayfası (irs.gov/payments), büyük ölçekli bir fatura sistemine örnektir: bakiyenizi (bir bildirim veya çevrimiçi hesap aracılığıyla) kontrol eder, ardından banka hesabı (Direct Pay) veya taksit planı ile ödeme yaparsınız. Mimari, hem fatura yaşam döngüsünü (düzenlendi, gönderildi, vadesi geçti, ödendi) hem de ödeme yaşam döngüsünü (başlatıldı, beklemede, tamamlandı, başarısız) ele almalıdır.

B2B SaaS veya özel web uygulamaları için genellikle PDF'ler oluşturan ve bir ödeme portalı barındıran bir fatura modülü inşa ederiz. Portal, birden çok yöntemi kabul etmelidir: kart, cüzdan veya banka havalesi. İşin püf noktası, fatura kimliğini ödeme ağ geçidindeki işlem kimliğine bağlamak ve ardından fatura durumunu güncellemek için webhook'ları kullanmaktır. Yaygın bir hata, ödeme ağ geçidinin barındırılan fatura özelliğine güvenmek ancak mutabakat üzerindeki kontrolü kaybetmektir. Kendi fatura kayıtlarımızı saklamayı ve ağ geçidini yalnızca bir ödeme işlemcisi olarak kullanmayı tercih ediyoruz.

// Example webhook handler for invoice payment confirmation
app.post('/webhooks/stripe', async (req, res) => {
  const event = req.body;
  if (event.type === 'checkout.session.completed') {
    const session = event.data.object;
    const invoiceId = session.metadata.invoice_id;
    await db.invoices.update({ id: invoiceId }, { status: 'paid' });
  }
  res.json({ received: true });
});

Yukarıdaki kod basit olsa da temel fikri göstermektedir: ağ geçidinin olayını kendi alan modelinize eşleyin. Metadata alanı cankurtaran halatınızdır. O olmadan, oturumları eşleştirmek için Stripe'a sorgu yapmanız gerekir, bu da gecikme ve karmaşıklık ekler.

Sipariş Durumu: Ödeme Olaylarını Yaşam Döngüsüne Eşleme

Bir sipariş birçok durumdan geçebilir: pending_payment, payment_received, processing, fulfilled, cancelled. Ödeme olayı, tetikleyicilerden yalnızca biri olmalıdır. Temel mimari karar, bir durum makinesi mi yoksa daha basit bir durum alanı mı kullanılacağıdır. Dörtten fazla durumu veya karmaşık geçişleri olan (örneğin, bir sipariş 'payment_received' durumundan 'processing'e, oradan 'shipped'e geçebilir, ancak aynı zamanda 'pending_payment' durumundan 'cancelled'e de geçebilir) herhangi bir sistem için durum makinelerini şiddetle öneriyoruz. Rails'in StateMachines gem'i veya Node.js'de özel bir sonlu durum makinesi iyi çalışır.

Ödeme ağ geçitlerinden gelen webhook'lar doğrudan durum makinesine beslenmelidir. Örneğin, bir payment_intent.succeeded olayı, siparişi 'pending_payment' durumundan 'payment_received' durumuna geçirmelidir. Ancak yarış koşullarına karşı korunun: webhook iki kez gelirse (çoğu ağ geçidi en az bir kez teslimatı garanti eder), durum makineniz idempotent olmalıdır; yani aynı mevcut durumdan aynı sonraki duruma geçiş bir hiç işlemi olmalıdır. Her webhook ile bir event_id saklayarak yinelenenleri ortadan kaldırıyoruz.

Idempotentlik isteğe bağlı değildir. Ödeme webhook işleyiciniz idempotent değilse, sonunda bir müşteriyi iki kez fatura eder veya hayalet siparişler oluşturursunuz. Bunu normal yük altında test etmek zordur; CI hattımızda gecikmeli ve yinelenen webhook'ları simüle ediyoruz.

Sipariş durumunun müşterilere de gösterilmesi gerekir. Basit bir durum sayfası (bir ilerleme çubuğu gibi) işe yarar, ancak yalnızca temel geçişler doğruysa. Ön uçun, sipariş durumunu önbelleğe alan bir API'yi sorguladığı sistemler gördük — ancak webhook işlenmemişse önbellek güncel olmayabilir. Çözüm, durum değişikliklerini iten gerçek zamanlı bir kanal (WebSocket veya Sunucu Tarafından Gönderilen Olaylar) kullanmaktır, böylece webhook işlendiğinde kullanıcı arayüzü anında güncellenir. Daha basit projeler için, 30 saniyelik bir TTL'ye sahip kısa ömürlü bir önbellek kabul edilebilir.

DigiForge'un Görüşü: Bir Ödeme Entegrasyon Katmanı Oluşturun, Karmaşa Değil

Projelerimizde düzinelerce ödeme yöntemini entegre ettikten sonra tavsiyemiz, ödeme işlemlerini ince bir hizmet katmanı arkasında soyutlamanızdır. Bu katman, her ödeme sağlayıcısının olaylarını ortak bir olay biçimine normalleştirmeli, yeniden denemeleri yönetmeli ve bir işlem günlüğü tutmalıdır. Sipariş sistemi asla doğrudan Stripe, Paytm veya herhangi bir ihraççı ile konuşmaz; ödeme hizmetinizle konuşur. Bu, sipariş mantığına dokunmadan yeni ödeme yöntemleri (örneğin, bir stablecoin kartı) eklemeyi çok daha kolay hale getirir.

Ayrıca faturaları, sipariş üzerinde yalnızca bir durum değil, ayrı bir alan olarak ele almanızı öneririz. Bir faturanın kendi yaşam döngüsü vardır (taslak, gönderildi, vadesi geçti, ödendi) ve birden çok siparişle (örneğin, aylık bir abonelik) ilişkilendirilebilir. Benzer şekilde, sipariş durumu, kısmi ödemeler, iadeler ve geri ödemeler dahil tüm olası geçişleri yöneten bir durum makinesi tarafından yönlendirilmelidir.

Sıfırdan bir ödeme entegrasyonu oluşturuyorsanız, desteklemeyi planladığınız tüm ödeme yöntemlerini haritalayarak ve yaydıkları ortak olayları belirleyerek başlayın. Ardından durum makinenizi ve webhook işleyicinizi tasarlayın. Bunu doğru yapın, gerisi tesisat işidir. Mimarisi hakkında ikinci bir görüş isterseniz, DigiForge ekibi sizi birkaç gece geç saatlere kadar ayakta kalmaktan kurtaracak kadar çok uç durum görmüştür.