Banka Entegrasyonu: Açık Bankacılık (ÖHVPS), MT940 ve Sanal POS Teknik Rehberi

"Banka entegrasyonu" tek bir şey değildir; Türkiye'de birbirine karıştırılan üç ayrı teknik yoldan biridir ve hangisine ihtiyacınız olduğunu doğru seçmek projenin en kritik kararıdır. (1) Hesap hareketi okuma — muhasebe ve mutabakat için, klasik yolu MT940/MT942 ekstre dosyalarıdır. (2) Açık bankacılık (ÖHVPS) — TCMB mevzuatı ve BKM API geçidi üzerinden hesap bilgisi ve ödeme emri başlatma; yalnızca TCMB tarafından yetkilendirilmiş kuruluşlar kullanabilir. (3) Sanal POS — kartla tahsilat, tamamen ayrı bir dünya. Bu rehber üçünü ayırır, her birinin gerçek teknik gereksinimlerini verir ve hangi durumda hangisini seçeceğinizi netleştirir.

Bu yazının en önemli cümlesi şudur: açık bankacılık API'larına doğrudan bağlanmak, çoğu şirket için hukuken mümkün değildir. Bunu baştan bilmeyen ekipler haftalarca yanlış dokümantasyonda dolaşır. Aşağıda neden ve alternatifi anlatılıyor.

Önce Karar: Hangi "Banka Entegrasyonu"na İhtiyacınız Var?

İhtiyaç	Doğru yol	Lisans gerekir mi?
"Hesabıma gelen havaleleri ERP'ye otomatik işleyeyim"	MT940/MT942 ekstre veya bankanın kurumsal entegrasyon servisi	Hayır — kendi hesabınızın verisi
"Toplu ödeme/maaş dosyası göndereyim"	Bankanın kurumsal ödeme dosyası / nakit yönetimi servisi	Hayır
"Kullanıcılarımın başka bankalardaki hesaplarını uygulamamda göstereyim"	ÖHVPS — Hesap Bilgisi Hizmeti (HBH)	Evet — HBHS yetkisi
"Kullanıcı kartsız, banka hesabından ödeme yapsın"	ÖHVPS — Ödeme Emri Başlatma Hizmeti (ÖBH)	Evet — ÖBHS yetkisi
"Sitemden kredi kartıyla tahsilat yapayım"	Sanal POS / ödeme kuruluşu	Hayır (sağlayıcı lisanslıdır)

Gelen taleplerin büyük çoğunluğu ilk iki satırdır: şirket kendi hesabının hareketlerini otomatik işlemek ister. Bunun için açık bankacılığa hiç ihtiyaç yoktur ve açık bankacılık yolu bu iş için hem gereksiz hem de kapalıdır.

Yol 1 — Hesap Hareketi Okuma: MT940 ve MT942

MT940, SWIFT mesaj tiplerinden biridir ve hesap ekstresinin standart makine-okunur halidir: açılış bakiyesi, dönem içindeki tüm hareketler ve kapanış bakiyesi. MT942 ise gün içi (interim) hareket bildirimidir — gün kapanmadan, o ana kadarki hareketleri verir.

Türkiye'de büyük bankaların tamamı MT940/MT942 üretir ve dosyayı e-posta, FTP/SFTP ya da SWIFT BIC adresine mesaj olarak iletir. Bu, "API" olmadığı için modası geçmiş gibi görünür; oysa muhasebe entegrasyonunun en sağlam ve en az bakım isteyen yoludur.

MT940 yapısı: alan etiketleri

Etiket	İçerik
:20:	İşlem referans numarası
:25:	Hesap kimliği (IBAN veya hesap no)
:28C:	Ekstre numarası / sayfa numarası
:60F:	Açılış bakiyesi (borç/alacak, tarih, para birimi, tutar)
:61:	Hareket satırı — valör, muhasebe tarihi, D/C, tutar, işlem tipi, referans
:86:	Hareketin serbest metin açıklaması (gönderen adı, açıklama)
:62F:	Kapanış bakiyesi

MT940'ın en sinsi tarafı :86: alanıdır. Bu alan serbest metindir ve her bankanın kendi biçimi vardır. "Gönderen adı" bir bankada sabit bir konumdadır, diğerinde noktalı virgülle ayrılmış anahtar-değer çiftleri arasındadır, bir üçüncüsünde kırpılmıştır. Bu yüzden:

• Ayrıştırıcıyı banka bazında yazın. Tek bir "evrensel MT940 parser" yazmaya çalışmak, sahada her zaman kaybedilen bir bahistir. Ortak bir arayüz + banka başına strateji sınıfı kullanın.
• Tutarı asla float ile taşımayın. MT940 tutarları virgüllü yazılır (1234,56). float'a çevirmek kuruş farkı üretir; tutarları tam sayı kuruş veya decimal olarak saklayın.
• Tekilleştirme anahtarı kurun. Aynı ekstre iki kez indirilebilir, bir gün iki kez gönderilebilir. Hareket için deterministik bir parmak izi üretin: hesap + valör + tutar + D/C + banka referansı.

<?php
// Idempotent hareket kaydi - ayni ekstre iki kez islenirse cift kayit olusmaz
$parmakIzi = hash('sha256', implode('|', [
    $hesapIban,
    $hareket['valor'],        // Y-m-d
    $hareket['tutarKurus'],   // int, kurus cinsinden
    $hareket['yon'],          // 'D' | 'C'
    $hareket['bankaReferansi'],
]));

BankaHareketi::updateOrCreate(
    ['parmak_izi' => $parmakIzi],
    [
        'hesap_iban'   => $hesapIban,
        'valor'        => $hareket['valor'],
        'tutar_kurus'  => $hareket['tutarKurus'],
        'yon'          => $hareket['yon'],
        'aciklama'     => $hareket['aciklama'],   // :86: ham metin
        'ham_satir'    => $hareket['ham'],        // :61: ham satir - SAKLA
        'eslesme_durumu' => 'beklemede',
    ]
);

Ham satırı saklayın. Ayrıştırıcınızda bir hata bulduğunuzda, ham veriyi saklamadıysanız geçmiş kayıtları yeniden işleyemezsiniz. Bu, mutabakat projelerinde en sık yaşanan geri dönülemez hatadır.

ISO 20022 / CAMT.053 geçişi

MT940'ı da içeren SWIFT MT mesaj tipleri uzun vadede ISO 20022 XML formatlarıyla (CAMT.053 hesap ekstresi, CAMT.052 gün içi, PAIN.001 ödeme talimatı) değiştirilmek üzere planlanıyor. Bugün yeni bir entegrasyon yazıyorsanız pratik tavsiye: iç veri modelinizi MT940'a göre değil, ISO 20022'nin kavramlarına göre kurun (hareket, karşı taraf, uçtan uca referans, amaç kodu). Böylece geçiş geldiğinde ayrıştırıcıyı değiştirirsiniz, tüm uygulamayı değil.

Yol 2 — Açık Bankacılık (ÖHVPS): Kimin Kullanabileceği

Türkiye'de açık bankacılığın hukuki dayanağı 6493 sayılı Kanunun 12'nci maddesi ve 1 Aralık 2021 tarihli, 31676 sayılı Resmî Gazete'de yayımlanan "Ödeme Hizmetleri ve Elektronik Para İhracı ile Ödeme Hizmeti Sağlayıcıları Hakkında Yönetmelik"tir. Teknik standart ise TCMB Ödeme Sistemleri ve Finansal Teknolojiler Genel Müdürlüğü'nün yayımladığı "ÖHVPS API İlke ve Kuralları" dokümanıdır. Tasarım, Avrupa Birliği'nin PSD2 düzenlemesiyle uyumludur.

Aktörler

Kısaltma	Türkçe	PSD2 karşılığı
HHS	Hesap Hizmeti Sağlayıcısı (banka, EPK, ödeme kuruluşu)	ASPSP
YÖS	Yetkili Ödeme Hizmeti Sağlayıcısı	TPP
HBHS	Hesap Bilgisi Hizmeti Sağlayıcısı	AISP
ÖBHS	Ödeme Emri Başlatma Hizmeti Sağlayıcısı	PISP
ÖHK	Ödeme Hizmeti Kullanıcısı (müşteri)	PSU
GKD	Güçlü Kimlik Doğrulama	SCA

Kritik nokta: ÖHVPS API'larını çağıran taraf YÖS'tür ve YÖS olmak TCMB yetkilendirmesi gerektirir. "Kullanıcılarımın banka hesaplarını uygulamamda göstereyim" diyen bir yazılım şirketi, bu yetkiyi almadan doğrudan bağlanamaz. İki gerçekçi seçenek vardır: (a) yetkilendirilmiş bir YÖS ile çalışıp onun sunduğu arayüzü tüketmek, (b) kendi yetkilendirme sürecinizi başlatmak — ki bu bir yazılım projesi değil, bir kurumsal lisans projesidir.

Kaynak URI yapısı

Standart, URI yolunu şöyle tanımlar:

[hhs-yol-on-eki]/ohvps/[kaynak-grubu]/[surum]/[kaynak]/[kaynak-no]/[alt-kaynak]

# kaynak-grubu: "hbh" (hesap bilgisi) veya "obh" (odeme emri baslatma)
# surum       : "s1.0", "s1.1" ...

HHS'ler kendi alan adlarında yayımlar; BKM API geçidi üzerinden erişim ise tek bir merkezden yapılır:

# Odeme Emri Baslatma (OBH)
https://apigw-prod.bkm.com.tr/api/main/ohvps/obh/s1.0/odeme-emri-rizasi
https://apigw-prod.bkm.com.tr/api/main/ohvps/obh/s1.0/odeme-emri

# Hesap Bilgisi (HBH)
https://apigw-prod.bkm.com.tr/api/main/ohvps/hbh/s1.0/hesap-bilgisi-rizasi
https://apigw-prod.bkm.com.tr/api/main/ohvps/hbh/s1.0/hesaplar
https://apigw-prod.bkm.com.tr/api/main/ohvps/hbh/s1.0/hesaplar/1234/islemler
https://apigw-prod.bkm.com.tr/api/main/ohvps/hbh/s1.0/hesaplar/1234/bakiye

# Guclu Kimlik Dogrulama
https://apigw-prod.bkm.com.tr/api/main/ohvps/gkd/s1.0/erisim-belirteci

# Saglik kontrolu - her API icin zorunlu
GET /hbh/s1.0/health   ->  { "status": "UP" }   // "UP" | "DOWN"

Aynı HHS'nin kendi yayınıyla BKM geçidi arasındaki eşleşme şöyledir: https://xbank.com.tr/api-portal/ohvps/hbh/s1.0/hesaplar ≡ https://apigw-prod.bkm.com.tr/api/main/ohvps/hbh/s1.0/hesaplar.

Zorunlu HTTP başlıkları

İstek başlıkları standartta ayrıntılı tanımlıdır; en kritikleri:

Başlık	Anlamı
X-Request-ID	Çağrıya özgü talep kimliği. Idempotent işlemlerde aynı değer, akışın her adımında farklı değer kullanılır.
X-Group-ID	İşlem akışına özgü kimlik. Aynı rızaya ait tüm isteklerde aynı değer.
X-ASPSP-Code	İsteğin iletildiği HHS kodu (4 karakter)
X-TPP-Code	İsteği gönderen YÖS kodu (4 karakter)
PSU-Initiated	E: işlemi kullanıcı başlattı · H: sistem başlattı. Sorgu limitleri buna göre uygulanır.
PSU-IP-Adress, PSU-User-Agent, PSU-Device-ID, PSU-GEO-Location	Kullanıcı cihaz bağlamı (koşullu)
X-Access-Token	GKD sonrası kullanılan erişim simgesi
X-JWS-Signature	Gövdenin ayrılmış (detached) JWS imzası

Başlık isimleri büyük-küçük harfe duyarlı olmamalıdır: x-request-id ile X-Request-ID sunucu tarafında aynı şekilde işlenebilmelidir.

Rıza (consent) durum makinesi

Açık bankacılık entegrasyonunun kalbi rızadır, veri çekme değil. Standart, rızanın alabileceği durumları açıkça tanımlar:

B : Yetki Bekleniyor         // ilk riza talebinde
Y : Yetkilendirildi          // basarili GKD sonrasi yetKod uretildiginde
K : Yetki Kullanildi         // erisim belirteci alindiginda
E : Yetki odeme emrine donustu   // OBHS icin
S : Yetki Sonlandirildi
I : Yetki Iptal

İptal durumu ayrıca detay koduyla zenginleştirilmiştir — 01 yeni rıza talebiyle iptal, 02 kullanıcı isteğiyle HHS üzerinden iptal, 03 kullanıcı isteğiyle YÖS üzerinden iptal, 04/05/06 süre aşımı, 07–16 arası çeşitli GKD iptalleri (mükerrer çağrı, TCKN uyuşmazlığı, uygun ürün bulunmaması, başarısız GKD vb.).

Tasarım tavsiyesi: bu durumları kendi veritabanınızda birebir modelleyin ve geçişleri (B → I/01 gibi) kayıt altına alın. Müşteri "neden hesabımı göremiyorum" diye sorduğunda, doğru cevabı ancak iptal detay kodunu sakladıysanız verebilirsiniz. Bu, teknik bir tercih değil, destek maliyetini belirleyen bir karardır.

Sorgu limitleri — mimarinizi bunlar belirler

Standart, kullanıcının başlatmadığı sistemsel sorgular için net limitler koyar:

• Bireysel ÖHK'lar için: hesap bazında günde en fazla 4 sorgu
• Kurumsal ÖHK'lar için: hesap bazında saatte en fazla 12 sorgu

Bu, "her 5 dakikada bir bakiye çek" tarzı bir tasarımı baştan imkânsız kılar. Ürününüz gerçek zamanlı bakiye gösterimi vaat ediyorsa, bu vaadi ya kullanıcı tetikli sorgulara (PSU-Initiated: E) dayandırmalı ya da baştan değiştirmelisiniz. Ayrıca HHS'lerin yıl bazında %99,75 erişilebilirlik hedefiyle kurgulaması beklenir ve her API için /health uç noktası zorunludur; geçit, DOWN dönen ya da yanıt vermeyen HHS'ye isteği iletmez.

Yol 3 — Sanal POS: Ayrı Bir Dünya

Kartla tahsilat, ÖHVPS ile hiçbir teknik ortaklığı olmayan üçüncü yoldur. Burada muhatabınız ya doğrudan bir bankanın sanal POS servisi ya da bir ödeme kuruluşudur. Ortak teknik unsurlar: 3D Secure yönlendirme akışı, ön provizyon/kesinleştirme ayrımı, kısmi iade, taksit ve komisyon tabloları, mutabakat dosyaları.

Sağlayıcı seçimi ve entegrasyon desenlerini ayrı bir yazıda ele aldık: Ödeme Sistemleri Entegrasyonu: Stripe, iyzico, PayTR. Hizmet tarafındaki kapsamımız için ödeme sistemi entegrasyonları sayfasına bakabilirsiniz.

Mutabakat: Entegrasyonun Asıl Zor Kısmı

Teknik ekipler genellikle "hareketleri çekmek"le işin bittiğini düşünür. Gerçekte işin %70'i eşleştirmedir: gelen 1.847,50 TL'lik havalenin hangi faturaya ait olduğunu bulmak.

Sahada işe yarayan kural seti, öncelik sırasıyla:

1. Açıklamada referans kodu: müşteriye ödeme yaparken açıklamaya yazması için tekil bir kod verin. En güvenilir yöntem budur ve tamamen sizin kontrolünüzdedir.
2. Sanal IBAN / alt hesap: her müşteriye ayrı bir IBAN tahsis edilebiliyorsa, eşleştirme sorunu tamamen ortadan kalkar. Bankanızın kurumsal ürünleri arasında bunu sorun.
3. Tutar + tarih penceresi: açık bakiyesi tam bu tutar olan tek bir fatura varsa eşleştir. Birden fazla adaysa otomatik eşleştirme yapma — operasyona düşür.
4. Gönderen unvanı benzerliği: yalnızca destekleyici sinyal olarak kullanın, tek başına asla.

Mutabakat sisteminin kalite ölçüsü "otomatik eşleşme oranı" değil, "yanlış eşleşme sayısı"dır. Yanlış eşleşmiş bir tahsilat, eşleşmemiş bir tahsilattan kat kat pahalıdır: müşteriye yanlış bakiye gösterir, yanlış kişiye hizmet açar ve muhasebede geriye dönük düzeltme gerektirir. Eşik değerinizi buna göre muhafazakâr kurun.

ERP tarafıyla bağlantı kuran mimariler için ERP entegrasyonları sayfamıza bakabilirsiniz.

Süre ve Maliyet

ininia'da yazılım geliştirme 300–400 USD/adam-gün bandında, adam-gün dökümüyle fiyatlanır. Bir banka entegrasyonu teklifini değerlendirirken (bizden ya da başkasından) dökümde şu kalemlerin ayrı ayrı görünmesini isteyin — toplu verilen rakam, kapsamın anlaşılmadığının işaretidir:

• Ekstre alımı (kanal: SFTP/e-posta/servis) ve dosya yönetimi
• Banka başına ayrıştırıcı — bu kalem banka sayısıyla çarpılır, sabit değildir
• Tekilleştirme ve ham veri saklama
• Eşleştirme kural motoru + manuel eşleştirme arayüzü
• Muhasebe/ERP tarafına yazma
• İzleme, alarm ve günlük mutabakat raporu

Kendi kapsamınız için hızlı bir aralık görmek isterseniz proje fiyat hesaplama aracımızı kullanabilirsiniz.

Sıkça Sorulan Sorular

Açık bankacılık API'larına lisanssız bağlanabilir miyim?

Hayır. ÖHVPS servislerini çağıran taraf YÖS'tür ve bu sıfat TCMB yetkilendirmesi gerektirir. Kendi şirketinizin kendi hesabının verisine erişmek istiyorsanız zaten ÖHVPS'ye ihtiyacınız yok — bankanızın kurumsal entegrasyon servisleri veya MT940 yeterlidir.

MT940 mı, API mi tercih etmeliyim?

Kendi hesabınızın muhasebe entegrasyonu için MT940 hâlâ en sağlam yoldur: bankadan bağımsız standart, sürüm kırılması az, kurulumu basit. Gerçek zamanlılık gerekiyorsa MT942 (gün içi) ekleyin ya da bankanızın kurumsal servislerini sorun.

Her banka için ayrı ayrıştırıcı yazmak zorunda mıyım?

Pratikte evet. MT940'ın :61: ve özellikle :86: alanlarının kullanımı bankadan bankaya değişir. Ortak bir arayüz tanımlayıp banka başına strateji sınıfı yazın; tek bir evrensel ayrıştırıcı hedefi sahada tutmaz.

Açık bankacılıkta hesap bakiyesini ne sıklıkla sorgulayabilirim?

Kullanıcının başlatmadığı sistemsel sorgular için standart limit koyar: bireysel kullanıcılarda hesap bazında günde 4, kurumsal kullanıcılarda hesap bazında saatte 12 sorgu. Kullanıcı tetikli sorgular PSU-Initiated: E ile ayrılır.

ÖHVPS ile sanal POS arasındaki fark nedir?

ÖHVPS, kullanıcının banka hesabı üzerinden bilgi paylaşımı ve ödeme emri başlatmayı düzenler; kart devreye girmez. Sanal POS ise kart tabanlı tahsilattır. Farklı mevzuat, farklı sağlayıcı, farklı teknik akış — ikisi birbirinin alternatifi değildir.

Mutabakat otomasyonunda hedef eşleşme oranı ne olmalı?

Tek bir doğru rakam yok; oran, ödeme akışınızın yapısına bağlıdır. Referans kodu veya sanal IBAN kullanabiliyorsanız oran yüksek olur, serbest açıklamalı havalelerde düşük kalır. Doğru hedef, oranı yükseltmek değil yanlış eşleşmeyi sıfıra yaklaştırmaktır; belirsiz durumlar otomatik eşleşmemeli, operasyona düşmelidir.

Banka entegrasyonunda hangi veriler KVKK kapsamındadır?

Hesap hareketlerindeki gönderen ad-soyad, IBAN ve açıklama metni kişisel veri içerir. Bu veriyi işlerken saklama süresi, erişim yetkilendirmesi ve loglama disiplininizi baştan tanımlayın; ham ekstre dosyalarını erişimi kısıtlı bir alanda tutun. Genel yaklaşımımız güvenlik merkezi sayfasında.

Sonuç

Banka entegrasyonu projelerinde kaybedilen zamanın çoğu kod yazarken değil, yanlış yolu seçmiş olmaktan kaynaklanır: kendi hesabının ekstresini okumak isteyen bir ekip haftalarca açık bankacılık mevzuatında dolaşır, ya da gerçek zamanlı bakiye vaat eden bir ürün sorgu limitlerini üretime çıktıktan sonra keşfeder. Doğru sıra şudur: önce ihtiyacın hangi kategoriye düştüğünü netleştirin, sonra o kategorinin kısıtlarını (lisans, limit, format çeşitliliği) mimariye yansıtın, en son kod yazın.

ininia olarak banka ve ödeme entegrasyonları, ekstre işleme hatları ve mutabakat otomasyonu kuruyoruz. Kapsamımızı banka entegrasyonları ve finans & fintech sayfalarında bulabilir, kendi projeniz için iletişim sayfasından yazabilirsiniz.

Kaynaklar: TCMB Ödeme Sistemleri ve Finansal Teknolojiler Genel Müdürlüğü, "Ödeme Hizmetleri Veri Paylaşım Servisleri (ÖHVPS) API İlke ve Kuralları" Sürüm 1.0.0 (Şubat 2022) — URI yapısı, BKM API geçidi adresleri, HTTP başlıkları, rıza durum kodları ve sorgu limitleri buradan alınmıştır. Mevzuat dayanağı: 6493 sayılı Kanun md.12 ve 01.12.2021 tarihli 31676 sayılı Resmî Gazete'de yayımlanan ilgili yönetmelik. Standart sürümlenir; üretime çıkmadan önce güncel sürümü teyit edin.