Fintech ve Ödeme Kuruluşları İçin Güvenli API Geliştirme
Para hareketi olan bir sistemde hatanın maliyeti bir hata mesajı değil, bir mutabakat farkıdır. Idempotency anahtarı, imzalı webhook, değişmez işlem kaydı ve günlük otomatik mutabakatı sonradan eklenen önlemler olarak değil, tasarımın ilk kararı olarak kuruyoruz.
- Idempotent ödeme uçları
- İmzalı ve tekrar korumalı webhook
- Değişmez işlem kaydı
- Otomatik mutabakat akışı
Sistem çalışıyor; sorun çalışmadığı anlarda çıkıyor.
Ödeme akışlarının çoğu mutlu senaryoda kusursuz görünür. Maliyet, zaman aşımı, tekrar ve kısmi başarı gibi arada kalan durumlarda birikir.
- Zaman aşımından sonra çift işlemYanıt gelmeyince istek tekrarlanıyor, ilk istek aslında işlenmiş oluyor. Müşteri iki kez ücretlendiğini şikâyetle bildiriyor.
- Webhook iki kez düşüyorSağlayıcı teslimatı garanti altına almak için tekrar gönderiyor; alıcı taraf her çağrıda yeni kayıt açtığı için bakiye şişiyor.
- Gelen çağrının kaynağı doğrulanmıyorUç nokta dışarıya açık ve imza kontrolü yok. Ödeme bildirimi görünümündeki herhangi bir çağrı sistemde durum değiştirebiliyor.
- Mutabakat ay sonunda elle yapılıyorExcel'de eşleştirme günler alıyor, fark bulunduğunda üzerinden haftalar geçmiş oluyor. Kaynağa geri gitmek neredeyse imkânsız.
- Kim neyi ne zaman değiştirdi belli değilİşlem durumu elle düzeltilebiliyor ama düzeltmenin kaydı tutulmuyor. Denetim sorusuna verilecek yanıt tahminden ibaret.
- Kısmi iade ve iptal akışı eksikAna akış yazılmış, iade ve iptal sonradan eklenmiş. Durum makinesinde boşluk kaldığı için bazı işlemler arada asılı kalıyor.
Önce hata senaryosu, sonra mutlu senaryo.
Ödeme API'si tasarımına 'ne ters gidebilir' listesiyle başlıyoruz. Tasarım kararlarının çoğu bu listeden çıkıyor; mutlu senaryo zaten kendiliğinden çalışıyor.
- İşlem durum makinesiBir işlemin alabileceği tüm durumlar ve geçişler yazılı hale gelir: beklemede, başarılı, başarısız, kısmi iade, tam iade, iptal, süresi dolmuş.TeslimDurum diyagramıGeçiş kurallarıUç durum listesi
- Idempotent uçlarPara hareketi yaratan her uç nokta idempotency anahtarı ister. Aynı anahtarla gelen ikinci istek yeni işlem açmaz, ilk sonucu döndürür.TeslimAnahtar politikasıTekrar yanıt davranışıSaklama süresi kararı
- İmzalı ve korumalı webhookGelen bildirimlerde imza ve zaman damgası doğrulanır; tekrar oynatma engellenir. Giden webhook'larda aynı disiplin karşı tarafa sunulur.Teslimİmza doğrulamaTekrar korumasıYeniden deneme planı
- Değişmez işlem kaydıKayıtlar üzerine yazılmaz; her değişiklik yeni bir satır olarak eklenir. Geçmiş, sonradan düzeltilemeyen bir zincir halinde durur.TeslimOlay tablosuAudit logDeğişiklik izleri
- Otomatik mutabakatSağlayıcı dosyası veya API kayıtları iç kayıtla günlük karşılaştırılır; eşleşmeyen satırlar sahibi olan bir listeye düşer.TeslimEşleştirme kurallarıFark listesi ekranıGünlük özet raporu
- Sandbox ve hata tatbikatıZaman aşımı, çift bildirim ve sağlayıcı arızası sandbox'ta bilerek tetiklenir. Sistem canlıya çıkmadan önce bu senaryolarda sınanır.TeslimSandbox ortamıHata senaryosu testleriKurtarma prosedürü
Mutabakat ve idempotency hazırlık tezgahı
Günlük işlem hacminizi seçin, bugün sizde bulunan kontrolleri açık bırakın. Tezgah, örnek bir hata dağılımı üzerinden aynı günün sonunda kaç isteğin tekrar riski taşıdığını, kaçının çift kayda dönüşebileceğini ve farkın ne zaman görüleceğini hesaplar. Tüm sayılar örnektir ve tarayıcınızda hesaplanır.
- Idempotency anahtarıÖdeme, iade ve transfer uçlarında zorunlu idempotency anahtarı tanımlayın; ilk sonucu saklayıp tekrar isteğe aynısını döndürün.
- Webhook imza ve zaman damgası doğrulamasıİmza doğrulamasını zorunlu hale getirin, zaman damgası penceresi dışındaki çağrıları reddedin ve doğrulanmayanları ayrı kaydedin.
- Kontrollü yeniden denemeÜstel geri çekilmeli yeniden deneme ve ölü mektup kuyruğu kurun; sonuçsuz işlemler operasyon listesine düşsün.
- Günlük otomatik mutabakatSağlayıcı dosyasını veya API kayıtlarını günlük çeken eşleştirme işi kurun; eşleşmeyen satırlar sahibi olan bir ekrana düşsün.
Hesapta kullanılan örnek varsayımlar
- İsteklerin binde beşi zaman aşımına uğruyor (örnek varsayım).
- Zaman aşımına uğrayan isteklerin %60'ı istemci tarafından tekrar gönderiliyor (örnek varsayım).
- Sağlayıcı bildirimlerinin binde ikisi aynı olay için iki kez düşüyor (örnek varsayım).
- Bu oranlar sektör ortalaması veya W3 ölçümü değildir; yalnız kontrollerin etkisini karşılaştırmak içindir.
Bu tezgah, hata senaryolarının etkisini konuşulabilir hale getirmek için hazırlanmış basitleştirilmiş bir modeldir; gerçek sisteminizin ölçümü, denetim raporu veya mevzuat uygunluk değerlendirmesi değildir. Lisans, bildirim ve denetim yükümlülükleri kurumunuzun hukuk ve uyum biriminin sorumluluğundadır.
Para hareketi olan bir API'de standart kabul ettiğimiz katmanlar
Aşağıdakiler proje büyüklüğünden bağımsız olarak kapsamda yer alır; tartışma konusu hangilerinin olacağı değil, her birinin ne kadar derin kurulacağıdır.
- ErişimKimlik ve anahtar yönetimiOAuth 2.0 veya anahtar tabanlı erişim; üretim ve test anahtarları kesin olarak ayrılır.
- ErişimTaşıma güvenliğiGüncel TLS zorunlu; karşı taraf destekliyorsa karşılıklı sertifika doğrulaması (mTLS).
- TutarlılıkIdempotency katmanıAnahtar saklama, tekrar isteğe aynı yanıt ve anahtar ömrü politikası.
- TutarlılıkDurum makinesiİşlem geçişleri kod içinde dağınık değil, tek yerde tanımlı ve test edilebilir.
- BildirimWebhook güvenliğiİmza doğrulama, zaman penceresi, tekrar koruması ve doğrulanmayan çağrıların ayrı kaydı.
- BildirimKuyruk ve kurtarmaYeniden deneme, ölü mektup kuyruğu ve elle kurtarma ekranı; hiçbir işlem sessizce kaybolmaz.
- DenetimAudit logKim, ne zaman, hangi işlemi hangi gerekçeyle değiştirdi — sonradan düzeltilemeyen kayıt.
- DenetimMutabakat işiZamanlanmış eşleştirme, fark listesi, günlük özet ve uyarı eşikleri.
Uçları Node.js ile yazıyor, işlem bütünlüğü gereken yerlerde PostgreSQL üzerinde veritabanı düzeyinde tekillik ve işlem (transaction) garantisi kullanıyor, kuyruk ve anahtar saklama için Redis tercih ediyoruz. Sözleşmeyi OpenAPI ile yazıp Postman koleksiyonuyla teslim ediyoruz; kapsamın tamamı API geliştirme sayfasında.
Ödeme akışının müşteri tarafındaki ekranları web yazılım geliştirme, mobil uygulama içi ödeme akışları mobil yazılım geliştirme kapsamında ilerler. Dışa açık uçlarda bağımsız doğrulama isterseniz süreci sızma testi rehberimizde anlattığımız gibi planlıyoruz; muhasebe tarafına yazan entegrasyonlarda Logo ERP çözüm ortaklığı devreye giriyor.
Denetime hazır olmak, rapor üretmekten önce kayıt tutmaktır.
Bir denetim sorusu genellikle tek cümledir: 'Şu işlemde ne oldu?' Bu sorunun yanıtı, sistemin nasıl kayıt tuttuğuna göre ya birkaç saniyede ya da birkaç günde verilir.
- İşlem geçmişiHer durum değişikliği zaman, kaynak ve tetikleyici bilgisiyle ayrı satır; geçmiş üzerine yazılmaz.
- Elle müdahale kaydıOperasyon ekranından yapılan her düzeltme kullanıcı ve gerekçe ile birlikte kaydedilir.
- Erişim kaydıHangi kullanıcının hangi kaydı görüntülediği ayrıca tutulur; yetki değişiklikleri izlenir.
- Saklama ve arşivKayıtların ne kadar süre tutulacağı ve nasıl arşivleneceği, uyum biriminizin verdiği çerçeveye göre tanımlanır.
Saklama süresi, veri yerleşimi ve raporlama biçimi gibi başlıklar mevzuata ve kurumunuzun yükümlülüklerine göre değişir; bu kararları hukuk ve uyum biriminizle birlikte yazılı hale getirip teknik tarafta uyguluyoruz. Uygunluk beyanı vermiyoruz. Karar sürecinde bağımsız bir teknik görüş isterseniz teknik danışmanlık tek başına da alınabilir.
Örnek bir ilk faz: tek ödeme akışı, uçtan uca
Aşağıdaki plan, tek bir ödeme akışının (tahsilat, iade, bildirim) uçtan uca kurulması için hazırlanmış örnektir. Sizin planınız akış sayısı ve sağlayıcılar netleştikten sonra çıkar.
| Hafta | Ne yapılır | Hafta sonunda elinizde ne olur |
|---|---|---|
| 1. hafta | Durum makinesi ve hata senaryoları | Durum diyagramı, uç durum listesi |
| 2. hafta | Sözleşme ve idempotency politikası | OpenAPI tanımı, anahtar kuralları |
| 3–4. hafta | Tahsilat ve iade uçları | Idempotent uçlar, tekillik kısıtları |
| 5. hafta | Webhook güvenliği ve kuyruk | İmza doğrulama, yeniden deneme, ölü mektup kuyruğu |
| 6. hafta | Audit log ve operasyon ekranı | Değişmez kayıt, kurtarma listesi |
| 7. hafta | Mutabakat işi | Eşleştirme kuralları, fark listesi, günlük özet |
| 8. hafta | Hata tatbikatı ve devir | Sandbox senaryo testleri, çalışma kılavuzu |
İlk akış canlıda kararlı çalıştıktan sonra yeni ödeme yöntemleri aynı katmana eklenir: durum makinesi, idempotency ve mutabakat yeniden kurulmaz, yalnız sağlayıcıya özel eşleştirme yazılır.
- HizmetAPI GeliştirmeHizmetin tamamı: kapsam, süreç, teslimatlar ve teknoloji yığını.
- HizmetWeb Yazılım GeliştirmeÖdeme akışının müşteri ve operasyon ekranları tarafı.
- HizmetMobil Yazılım GeliştirmeUygulama içi ödeme akışları ve istemci tarafı tekrar davranışı.
- HizmetTeknik DanışmanlıkMimari ve kontrol seti için bağımsız teknik değerlendirme.
- ProjeTYS — Teklif Yönetim SistemiLogo ERP'ye çift yönlü yazan entegrasyon katmanı; kendi ürünümüz.
- RehberSızma testi (pentest) nedir?Dışa açık ödeme uçlarında bağımsız güvenlik doğrulaması.
- RehberHosting, VPS, bulut ve dedicated farkıİşlem kayıtlarının nerede tutulacağına karar verirken.
- RehberYazılım firması seçerken dikkat edilmesi gerekenlerFinansal sistem teklifi karşılaştırırken sorulacak sorular.
Sık sorulanlar
Idempotency, webhook doğrulama, mutabakat, kart verisi ve mevzuat sorumluluğu hakkında en çok sorulanlar.
Hata senaryolarınızı birlikte listeleyelim
Hangi sağlayıcılarla çalıştığınızı, hangi akışlarda fark yaşadığınızı ve bugün mutabakatı nasıl yaptığınızı anlatın; ilk görüşmede kontrol boşluklarını ve gerçekçi bir ilk faz kapsamını çıkaralım. Keşif görüşmesi ücretsizdir ve sizi bağlamaz.
- ✓ Keşif görüşmesi ücretsiz
- ✓ Kapsam netleşmeden fiyat vermiyoruz
- ✓ Uyum beyanı değil, teknik uygulama
Çift çekimi şikâyetten değil, mutabakattan öğrenin
Idempotency, imzalı webhook, değişmez işlem kaydı ve günlük otomatik mutabakatı tasarımın ilk kararı olarak kuruyoruz.