Kavramlar & Sözlük
Açık bankacılık kendine has bir sürü terimle gelir ve ilk bakışta bunlar korkutucu görünebilir. Bu sayfa, sistemde sık geçen kavramları günlük Türkçeyle, gerektiğinde küçük örneklerle açıklar. Buradaki birkaç dakikayı okuduğunuzda diğer sayfalar (Mimari, Akışlar) çok daha anlaşılır olur.
Temel kavramlar
Aşağıdaki kartlar en çok karşınıza çıkacak terimleri açıklıyor. Sırayla okumak zorunda değilsiniz; bir terime takıldıkça buraya dönebilirsiniz.
YÖS (TPP)
Yetkili Ödeme Hizmeti Sağlayıcısı. Kullanıcının izniyle, onun adına bankalara bağlanan üçüncü taraf şirkettir — yani bizim ürünümüz olan api-yos. Kullanıcının parasını kendi tutmaz; sadece bankalardan veri çeker ve kullanıcı adına ödeme başlatır. İngilizcesi TPP (Third Party Provider). Örneğin bir bütçe uygulaması, üç ayrı bankadaki hesaplarınızı tek ekranda toplayabilmek için YÖS rolündedir.
HHS (ASPSP)
Hesap/Hizmet Sağlayıcı — yani kullanıcının hesabının bulunduğu banka. Rızayı (izni) onaylatan, hesap ve kart verisini üreten ve ödeme sonucunu döndüren taraftır. Bizim sistemimiz veriyi hep buradan alır. Gerçek hayatta bu bir bankadır; testte ise api-hhs adlı simülatör tıpkı gerçek banka gibi davranarak bu rolü oynar.
ÖHVPS
Ödeme Hizmetleri ve Veri Paylaşımı Standardı (BKM v2.0.0). YÖS ile HHS'in birbiriyle nasıl konuşacağını belirleyen resmi Türkiye standardıdır. Alan adlarını, kodları, güvenlik ve imza kurallarını tek tek tanımlar. Sayesinde her banka aynı dili konuşur; biz her bankaya ayrı ayrı kod yazmayız. Bir nevi ortak sözlük ve trafik kuralları kitabı gibidir.
Rıza (Consent)
Kullanıcının verdiği açık izin. İki türü olur: 'bu bankadaki şu verilerime erişebilirsin' (hesap/bakiye) veya 'benim adıma şu ödemeyi yapabilirsin' (ödeme). Rıza olmadan hiçbir veri çekilmez ve hiçbir ödeme başlatılmaz — sistemin temel güvence noktasıdır. Her banka bağlantısı ve her ödeme, arka planda bir rızaya dayanır. Örneğin kullanıcı bir kez 'hesabımı görebilirsin' izni verdiğinde, o rıza geçerli oldukça bakiye tekrar tekrar sorulabilir.
GKD
Güçlü Kimlik Doğrulama. Kullanıcının bankada 'evet, bu işleme izin veriyorum' dediği onay adımıdır. İki yöntemi vardır: Yönlendirmeli (redirect — kullanıcı bankanın kendi sayfasına gider, orada onaylar ve geri döner) ve Ayrık (decoupled — kullanıcı bankanın mobil uygulamasından ya da SMS ile onaylar, sayfa değiştirmez). Amaç, işlemi gerçekten hesap sahibinin onayladığından emin olmaktır. Örneğin ödeme yaparken telefonunuza gelen bankacılık bildirimini onaylamanız bir GKD adımıdır.
yetKod (Yetki Kodu)
Kullanıcı bankada onayını verdikten hemen sonra bankanın bize verdiği tek kullanımlık, kısa ömürlü geçici koddur. Tek başına işe yaramaz; asıl erişim için bir sonraki adıma kapı açar. Batch bu kodu bankaya geri götürüp kalıcı bir erişim token'ına (bankadan veri çekmeye yarayan dijital anahtar) çevirir. Konser bileti gişesinden aldığınız fişi salon girişinde asıl bilete dönüştürmek gibidir.
PSU
Payment Service User — asıl banka müşterisi, yani son kullanıcının kendisi. Bir işlem yapılırken bankaya, bu işin kullanıcının o an başında olup olmadığı bilgisi de iletilir. Üç durum olur: kullanıcı o an ekranın başında (present / E), işlem otomatik/kullanıcısız yapılıyor (autonomous / O) ya da bir olaya tepki olarak tetiklendi (event / H). Örneğin gece otomatik çalışan bir düzenli ödeme 'kullanıcı başında değil' olarak işaretlenir; kullanıcının canlı bakiye sorusu ise 'başında' olur.
mTLS
Karşılıklı TLS (mutual TLS). Normal HTTPS'te sadece sunucu kimliğini kanıtlar; mTLS'te ise iki taraf da kendi sertifikasıyla 'ben gerçekten oyum' der. Böylece banka, kendisine bağlanan tarafın gerçekten bizim sistemimiz olduğundan emin olur. Bizim tarafta bu sertifikaları yalnızca Batch taşır — Public API taşımaz, çünkü o bankaya hiç bağlanmaz. İki kişinin de birbirine kimliğini gösterip el sıkışması gibi düşünülebilir.
JWS (Detached)
Giden mesajın gövdesinin PS256 yöntemiyle imzalanmasıdır (RFC 7797 standardı). İmza, mesajın yolda hiç değiştirilmediğini ve gerçekten bizden geldiğini kanıtlar. 'Detached' (ayrık) olması, imzanın mesaj gövdesinin içine karışmadan ayrı bir başlıkta taşındığı anlamına gelir. Banka da yanıtlarını aynı şekilde imzalar; imzasız veya imzası tutmayan bir yanıt gelirse reddedilir, çünkü sahte ya da bozulmuş olabilir.
SyncIntent (Niyet Kutusu)
Public API'nin Batch'e 'şu banka işini senin yapman lazım' diye bıraktığı nottur. Teknik adı outbox: yapılacak işi önce veritabanına bir kayıt olarak yaz, sonra arka planda sırayla işle. API işi kendisi yapmaz, sadece notu bırakır ve kullanıcıya hemen döner; Batch bu notları gelme sırasına göre okuyup yerine getirir. Bir restoranın mutfağa sipariş fişi asması gibidir — garson yemeği pişirmez, fişi asar, aşçı sırayla hazırlar.
BOLA İzolasyonu
Broken Object Level Authorization (nesne düzeyinde yetki) koruması. Bir kullanıcının, başka bir kullanıcının hesabına, kartına veya ödemesine — kimlik numarasını bilse bile — erişememesini sağlar. Böyle bir deneme yapılırsa sistem 'yetkin yok' bile demez, doğrudan 'bulunamadı' (404) döner; böylece o kaynağın var olup olmadığı bile sızmaz. Örneğin kullanıcı A, kullanıcı B'nin ödeme numarasını URL'ye yazsa bile sadece boş bir 'bulunamadı' yanıtı görür.
Idempotency (Tekrar Koruması)
Aynı yazma isteğinin yanlışlıkla iki kez gitmesi (örneğin ağ koptuğu için istemcinin tekrar denemesi) durumunda, işlemin yine de yalnızca bir kez gerçekleşmesini garanti eden mekanizmadır. Her istekle birlikte gönderilen Idempotency-Key başlığı sayesinde sistem 'bu isteği daha önce gördüm' der ve tekrar işlemez. En kritik yer ödemelerdir: kullanıcı butona iki kez bassa bile para yalnızca bir kez gider.
İmleç (Cursor) Sayfalama
Uzun listeleri (işlem geçmişi, ödemeler) parça parça getirirken kullanılan yöntemdir. Klasik 'sayfa 1, sayfa 2' yerine, son görülen kaydı işaret eden bir 'imleç' tutulur ve 'buradan sonrasını getir' denir. Bu, verinin arada değiştiği büyük listelerde bile kayma/tekrar olmadan tutarlı ve hızlı çalışır. Örneğin binlerce işlem arasında sayfa numarasıyla gezerken yeni işlem eklenince sıralar kaymaz.
Canlı tazeleme (?fresh=true)
Normalde sistem, veritabanındaki en son kayıtlı veriyi gösterir (hızlıdır). Bir sorguya ?fresh=true eklenirse, veri bankadan o an, anlık olarak güncellenir. Araya giren bir koordinatör, gereksiz banka çağrısı yapılmasını önler; gerçekten gerekiyorsa kısa bir süre bekleyip taze veriyi getirir. Örneğin kullanıcı 'bakiyem şu an tam olarak ne?' derse, ?fresh=true ile bankadan canlı bakiye çekilip gösterilir.
Wire sözlüğü (Türkçe alan ↔ İngilizce)
Bankaya giden ve bankadan gelen mesajlarda alan adları Türkçedir; bu, ÖHVPS standardının bir kuralıdır (örneğin bakiye alanının adı gerçekten "bakiye" olarak geçer). Sistemin kendi içinde ise okunabilirlik ve tutarlılık için İngilizce isimler kullanılır ("Balance" gibi). Bu Türkçe-İngilizce çeviri yalnızca bankaya bağlanan tek katmanda (Batch) yapılır; Türkçe alan adları sistemin geri kalanına hiç sızmaz. Aşağıdaki tablo, en sık geçen alanların iki dildeki karşılığını gösterir.
| Wire (Türkçe) | İç ad (İngilizce) | Anlamı |
|---|---|---|
rizaNo | ConsentReference | Rıza numarası — her izin için bankanın verdiği tekil kimlik |
rizaTip | ConsentType | Rıza tipi — H (hesap), O (ödeme), D (düzenli ödeme), I (ileri tarihli ödeme) |
yetKod | AuthorizationCode | Yetki kodu — onaydan sonra token'a çevrilen geçici kod |
hesaplar | Accounts | Hesap listesi — kullanıcının bankadaki hesapları |
bakiye | Balance | Bakiye — hesaptaki güncel tutar |
gkd.yonAdr | AuthorizationUrl | Onay yönlendirme adresi — kullanıcının onaya gideceği banka bağlantısı |
odmStm | PaymentSystem | Ödeme sistemi — H (havale), F (FAST), E (EFT); hangisi olacağına banka karar verir |
kmlkTur / kmlkVrs | IdentityType / IdentityValue | Kimlik tipi ve değeri (TCKN için K, VKN için V) |
Bağlantı / rıza durumları
Bir banka bağlantısı ya da rıza, kurulduğu andan itibaren birkaç durumdan geçer. Bu durumlar, işin hangi aşamada olduğunu tek kelimeyle anlatır. Aşağıda en baştan (beklemede) en sona (bağlı, iptal ya da başarısız) doğru sıralanmıştır.
Örneğin yeni bir banka bağlantısı önce Pending'te bekler; kullanıcı GKD ile onaylayınca Authorized olur; Batch token'ı alıp veriyi hazırlayınca Connected'a geçer. Onay verilmez ya da banka reddederse Failed, kullanıcı vazgeçerse Cancelled durumuna düşer.