İçindekiler

Ödeme hizmeti sağlayıcısı ile müşteri arasında tekil veya süreklilik arz eden ödeme işlemlerinin yürütülmesine ve mümkün olan durumlarda ödeme hesabının açılmasına ilişkin usul ve esasları belirleyen sözleşme

EPK

Elektronik Para Kuruluşu

Kanun kapsamında elektronik para ihraç etme yetkisi verilen tüzel kişi

Electronic Money Institution

EMI

FAST

Fonların Anlık ve Sürekli

Transferi

TCMB tarafından işletilen Fonların Anlık ve Sürekli Transferi

Sistemi

FAST TR-

Karekod

FAST-TR Karekod Teknik

İlke ve Kurallar Rehberi

TR Karekod’un FAST Sistemi aracılığıyla gerçekleşecek işlemlerde kullanılmasına ilişkin detaylı teknik ilke ve kurallarını içeren doküman

GKD

Güçlü Kimlik Doğrulama

Kimlik doğrulamada kullanılan ve bir bileşenin ele geçirilmesinin diğer bileşenin güvenliğini tehlikeye atmayacağı en az iki bileşenden oluşan, bu iki bileşenin de müşterinin bildiği, sahip olduğu veya biyometrik bir karakteristiği olan bileşen sınıflarından farklı ikisine ait olacak şekilde seçildiği yöntem

Strong Customer Authentication

SCA

İB

İşlem Bilgisi

Gerçekleştirilen işleme ilişkin işlem zamanını, işlemin niteliğini ve ödeme işlemi için ödeme emrinin masraf, komisyon ve ücretler de dahil hesabın borçlandırılacağı toplam tutarını ve ödemenin

göndereni ile alıcısını veya toplu ödeme emrinin masraf, komisyon

ve ücretler de dahil hesabın borçlandırılacağı toplam tutarını ve göndereni ile alıcılarını içeren bilgi

İDK

İşlem Doğrulama Kodu

Kimlik doğrulama yöntemlerinden biriyle kendisini sisteme tanıtan bir müşterinin gerçekleştirmek istediği işleme özgü olmak ve belirli bir geçerlilik süresi içinde işlem onayında kullanılmak üzere oluşturulan, finansal sonuç doğrunan işlemlerde kişiye onay anında ilgili işlem bilgisi (İB) ile birlikte gösterilen, alıcı veya tutarın değişmesiyle geçersiz hale gelen bilgi

Authentication Code

KOLAS

Kolay Adresleme Servisi

Fon transferlerinde hesap numarası ile ad soyad yerine kullanılan ve belirli bir hesap ile eşleştirilmiş telefon numarası, e-posta adresi, T.C. Kimlik Numarası (TCKN), Vergi Kimlik Numarası (VKN), Yabancı Kimlik Numarası veya Pasaport Numarası gibi Kolay Adres bilgilerinin kaydedilmesini, güncellenmesini ve sorgulamasını sağlayan katman servis

HBHS

Hesap Bilgisi Hizmeti

Sağlayıcısı

Kanunun 12 inci maddesinin birinci fıkrasının (g) bendinde tanımlanan ödeme hizmetini (hesap bilgisi hizmetini) sunan tüzel kişi

Account Information Service Provider

AISP

HHS

Hesap Hizmeti Sağlayıcısı

Nezdinde ödeme hesabı bulunan ödeme hizmeti sağlayıcısı

Account Servicing Payment Service Provider

ASPSP

ÖBHS

Ödeme Emri Başlatma Hizmeti Sağlayıcısı

Kanunun 12 inci maddesinin birinci fıkrasının (f) bendinde tanımlanan ödeme hizmetini (ödeme emri başlatma hizmetini) sunan tüzel kişi

Payment Initiation Service Provider

PISP

ÖDK

Ödeme Kuruluşu

Ödeme hizmeti sağlamak ve gerçekleştirmek için Kanun kapsamında yetkilendirilmiş tüzel kişi

Payment Institution

ÖH	Ödeme Hesabı	Ödeme hizmeti kullanıcısı adına açılan ve ödeme işleminin yürütülmesinde kullanılan hesap	Payment Account	PA
ÖHK	Ödeme Hizmeti Kullanıcısı (Müşteri)	Gönderen, alıcı veya her ikisi sıfatıyla belirli bir ödeme hizmetinden faydalanan gerçek veya tüzel kişi	Payment Service User	PSU
ÖHS	Ödeme Hizmeti Sağlayıcısı	5411 sayılı Kanun kapsamındaki bankalar, EPK, ÖDK ve PTT	Payment Service Provider	PSP
ÖHVPS	Ödeme Hizmetleri Veri Paylaşım Servisleri	Kanunun 12’nci maddesinin birinci fıkrasının (f) veya (g) bentlerinde yer alan ödeme hizmetlerinde kullanılan veri paylaşım servisleri
PÖS	Perakende Ödeme Sistemi	TCMB tarafından işletilen, işlemlerin Türk Lirası üzerinden gerçekleştiği Müşteriler Arası Türk Lirası Aktarım Sistemi
TR- Karekod	TR-Karekod İlke ve Kuralları	Ulusal karekod (TR Karekod) ilke ve kurallarının belirlendiği belge
YÖS	Yetkili Ödeme Hizmeti Sağlayıcısı	Ödeme emri başlatma hizmeti ve/veya hesap bilgisi hizmeti sunan tüzel kişi	Third Party Payment Service Providers	TPP

API İlke ve Kuralları|Şubat 2022 9

2. Kapsam ve Dayanak

12 Kasım 2019’da güncellenen “6493 sayılı Ödeme ve Menkul Kıymet Mutabakat Sistemleri, Ödeme Hizmetleri ve Elektronik Para Kuruluşları Hakkında Kanun”un (Kanun) 12’nci maddesine yeni eklenen ve Ödeme Hizmetleri Direktifi 2'de (Payment Services Directive 2, PSD2) bulunan iki yeni ödeme hizmeti aşağıdaki gibi tanımlanmıştır (Şekil-1: Ödeme Hizmetleri Veri Paylaşım Servisleri):

• Ödeme Emri Başlatma Hizmeti: ÖHK’nın isteği üzerine başka bir ödeme hizmeti sağlayıcısında bulunan ödeme hesabıyla ilgili sunulan ödeme emri başlatma hizmeti [Madde 12, birinci fıkra, (f) bendi]

• Hesap Bilgisi Hizmeti: ÖHK’nın onayının alınması koşuluyla, ÖHK’nın ödeme hizmeti sağlayıcıları nezdinde bulunan bir veya daha fazla ödeme hesabına ilişkin konsolide edilmiş bilgilerin çevrim içi platformlarda sunulması hizmeti [Madde 12, birinci fıkra, (g) bendi]

Şekil 1: Ödeme Hizmetleri Veri Paylaşım Servisleri (ÖHVPS)- tanıtım

Kanunun 14/A maddesinin ikinci fıkrasına göre, Kanunun 12’nci maddesinin birinci fıkrasının (f) veya (g) bentlerinde yer alan ödeme hizmetleri ile ilgili işlemlerin yürütülmesine ilişkin usul ve esaslar ile taraflarca uyulması gereken teknik ve operasyonel gereklilikler ikincil düzenlemeler uyarınca Türkiye Cumhuriyet Merkez Bankası (TCMB) tarafından belirlenir. Kanunun 12’nci maddesinin birinci fıkrasının (f) veya (g) bentlerinde yer alan ödeme hizmetlerinde kullanılan veri paylaşım servisleri ödeme hizmetleri veri paylaşım servisleri (ÖHVPS) olarak adlandırılmaktadır.

Ödeme Hizmetleri ve Elektronik Para İhracı ile Ödeme Hizmeti Sağlayıcıları Hakkında Yönetmelik’in (Yönetmelik) 59’uncu maddesinin birinci fıkrası uyarınca hazırlanan bu belgede söz konusu ödeme hizmetlerini sunacak ödeme hizmeti sağlayıcısının, ödeme hesabının bulunduğu ödeme hizmeti sağlayıcısının, varsa ilgili diğer tarafların ve bu hizmetlerin sunulması için taraflar arasında kurulacak bağlantının teknik ve operasyonel gereklilikleri açıklanmaktadır.

Düzenlemeler kapsamında yetkilendirilen üçüncü taraf hizmet sağlayıcısı (Yetkili Ödeme Hizmeti Sağlayıcısı, YÖS), ödeme hizmeti kullanıcılarının Hesap Hizmeti Sağlayıcıları (HHS) nezdindeki ödeme hesaplarına ulaşarak ödeme emri başlatma ve hesap bilgisi sağlama hizmetlerinden (ödeme hizmetleri veri paylaşım servislerinden) faydalanmasına aracılık eder. Ödeme hizmetleri veri paylaşım

servisleri kapsamında iki tip YÖS bulunmaktadır: 1) Hesap Bilgisi Hizmeti Sağlayıcısı (HBHS) ve 2)

Ödeme Emri Başlatma Hizmeti Sağlayıcısı (ÖBHS).

Hesap Bilgisi Hizmeti Sağlayıcısı (HBHS) ÖHK’nın farklı Hesap Hizmeti Sağlayıcıları (HHS) nezdindeki hesaplarının bilgilerini derleyerek çevrim içi platformlarda toplu şekilde sunar. Ödeme Emri Başlatma Hizmeti Sağlayıcısı (ÖBHS) ise talebi üzerine ÖHK’nın HHS’de bulunan ödeme hesabından ödeme işlemi başlatır.

ÖHVPS’nin üst düzey gösterimi Şekil-2’de verilmiştir.

Şekil 2: Ödeme Hizmetleri Veri Paylaşım Servisleri (ÖHVPS) -üst düzey gösterim

Ödeme Hizmetleri Veri Paylaşım Servislerinin HHS’ler tarafından BKM API Geçidi vasıtasıyla sunulduğu uygulama mimarisi ise Şekil-3’te sunulmuştur.

Şekil 3: ÖHVPS'nin BKM API Geçidi vasıtasıyla sunumu

3. Temel Prensipler

Bu bölümde Ödeme Hizmetleri Veri Paylaşım Servisleri (Hesap Bilgisi Hizmeti, Ödeme Emri Başlatma Hizmeti) için tanımlanan temel prensipler açıklanmaktadır.

3.1. Genel

• HHS’ler Yönetmeliğin 59. maddesinin beşinci fıkrası ve Ödeme ve Elektronik Para Kuruluşlarının Bilgi Sistemleri ile Ödeme Hizmeti Sağlayıcılarının Ödeme Hizmetleri Alanındaki Veri Paylaşım Servislerine İlişkin Tebliğin (Tebliğ) 23. maddesinin birinci fıkrası uyarınca, ödeme hizmetleri veri paylaşım servislerini BKM API Geçidi aracılığıyla HBHS ve ÖBHS’ye sunmakla yükümlüdür.

• Tebliğin 23. maddesinin ikinci fıkrası uyarınca ödeme emri başlatma hizmetinde açık iletişim servisinin tarafları ÖBHS ile HHS’dir.

• Tebliğin 23. maddesinin üçüncü fıkrası uyarınca hesap bilgisi hizmetinde açık iletişim

servisinin tarafları HBHS ile HHS’dir.

• Yönetmeliğin 60. maddesinin birinci fıkrası uyarınca müşteri, ödeme emri başlatma hizmetini ödeme hesabının çevrim içi olarak erişilebilir olduğu durumlarda, kullanmayı tercih edebilir.

• Yönetmeliğin 61. maddesinin birinci fıkrası uyarınca müşteri, hesap bilgisi hizmetini ödeme hesabının çevrim içi olarak erişilebilir olduğu durumlarda, kullanmayı tercih edebilir.

• Tebliğin 25. maddesi uyarınca HHS ve YÖS (ÖBHS ve HBHS) arasında bağlantı uçtan uca güvenli bir şekilde sağlanır. Bu amaçla iletim katmanında TLS (asgari 1.2 sürümü) ile şifreli iletişim sağlanır.

• Tebliğin 23. maddesinin dördüncü fıkrası uyarınca HHS tarafından sunulan ödeme hizmetleri veri paylaşım servislerini kullanan yetkilendirilmiş ödeme hizmeti sağlayıcılarının TCMB tarafından ilgili ödeme hizmeti için yetkilendirilmiş olduğu kontrol edilir.

• Tebliğin 25. maddesinin beşinci fıkrası uyarınca zaman damgası, 15/1/2004 tarihli 5070 sayılı Elektronik İmza Kanunu kapsamında tanımlanan zaman damgasına dayanır.

• API alan isimleri Türkçe olarak tanımlanmıştır. Ancak API başlığı (header) alanındaki alan isimleri özelinde, API Geçitleri tarafından otomatik olarak tanınabilmesi gözetilerek, İngilizce isimlendirme tercih edilmiştir.

3.2. İstem (Çağrı) ve Oturum

• Her istek biricik istek numarası ve ÖHK’lı işlemler için zaman damgası içerir. Birden fazla istek içeren işlem YÖS tarafından belirlenen çağrıya özgü talep kimliği (istek numarası: x- request-id) ve işlem akışına özgü talep kimliği (işlem grup numarası: x-group-id) değerleri kullanılarak HHS tarafından bir oturum yaklaşımı ile sürdürülür (Bknz. 3.15 İstek Başlığı).

• Oturum takibi ise işlem grup numarası ile yapılır. İşlem grup numarası da ÖHK’lı işlemler için zaman damgası ile birlikte ilgili tüm işlem verilerini içerecek şekilde kayıt altına alınır.

• Örneğin, bir ödeme emri başlatma işlemi birden fazla istekten oluşur. Her istek yukarıda belirtildiği gibi biricik istek numarası ve ÖHK’lı işlemler için zaman damgası içerir. Ancak işlemin oturum bütünlüğü işlem grup numarası ile sağlanır.

• Taraflar açtıkları oturumu işlem bütünlüğünü sağlayacak süre içerisinde xxxx xxxxx ve işlem biter bitmez kapatır.

3.3. RESTful API

API’ler, dünya ölçeğinde yaygın bir şekilde kullanılan Temsili Durum Transferi (Representational State Transfer, REST) mimari tarzı ve JavaScript Nesne Notasyonu (JavaScript Object Notation, JSON) veri formatlarına uygun olarak geliştirilir. En üst seviye Veri Tanımlama Dili (Data Description Language) ve en iyi uygulama örnekleri için JSON Şeması1 temel alınır.

3.4. Sürüm Yönetimi

API sonraki aşamalarda doğabilecek gereksinimleri ve daha karmaşık kullanım durumlarını karşılamak için sürümler halinde geliştirilir ve bu durum tasarım sırasında göz önünde bulundurulur.

API v1.0 sürümünde

• Vadesiz TL, yabancı para hesapları (gerçek ve tüzel kişilere ait ödeme hesapları), Kredili Mevduat Hesabı

• Tekil ödeme (Virman/Havale/FAST/Müşterilerarası TL Aktarım Sistemi)

• Hesap bilgisi hizmetleri

o Temel veya ayrıntılı hesap bilgisi

o Bakiye

1 xxxx://xxxx-xxxxxx.xxx/

o Gerçekleşen işlemler için Hesap hareketleri

• Karekodlu ödemelerdeki 01, 02 ve 03 akış türleri yer almaktadır.

Her sürüm değişikliğinde bir önceki sürüm belirli bir süre desteklenecektir. Diğer bir ifadeyle, sadece belirli bir süre için mevcut ve bir önceki sürüm aynı anda erişilebilir olacaktır.

3.5. Kaynak URI Yol Yapısı

YÖS’lerin başlattığı çağrılarda URI yolu aşağıdaki yapıyı takip eder:

[hhs-yol-ön-eki]/ohvps/ [kaynak-grubu]/ [sürüm]/ [kaynak]/[kaynak-no]/[alt-kaynak]

Bu, aşağıdaki unsurlardan oluşur:

• [hhs-yol-ön-eki]

İsteğe bağlı, HHS'ye özgü yol ön ekini ifade eder.

BKM API geçidi üzerinden yapılan çağrılarda BKM tarafından belirlenen sistem adı ve yol ön eki kullanılır.

• ohvps

Sabit metin “ohvps” (Ödeme Hizmetleri Veri Paylaşım Servisleri kısaltması)

• [kaynak-grubu]

Kaynak grubu, API’ye erişmek için kullanılan ödeme hizmetine (HBH, ÖBH) göre erişim adresi (end point) grubunu tanımlar (“hbh” veya “obh”).

• [sürüm]

API sürümünü ifade eder (“/s[ana-sürüm].[alt-sürüm]/”).

• [kaynak]/[kaynak-no]

Kaynak detaylarını ifade eder.

• [alt-kaynak]

Alt kaynak detaylarını ifade eder.

HHS, tüm kaynakları için aynı katılımcı yolu ön ekini ve sistem adını kullanmalıdır.

BKM API’lerine erişmek isteyen uygulamaların yetkilerine göre aşağıdaki API’lere abone olmaları

gerekmektedir:

OBH:

xxxxx://xxxxx-xxxx.xxx.xxx.xx/xxx/xxxx/xxxxx/xxx/x0.0/xxxxx-xxxx-xxxxxx xxxxx://xxxxx-xxxx.xxx.xxx.xx/xxx/xxxx/xxxxx/xxx/x0.0/xxxxx-xxxx

HBH:

xxxxx://xxxxx-xxxx.xxx.xxx.xx/xxx/xxxx/xxxxx/xxx/x0.0/xxxxx-xxxxxxx-xxxxxx xxxxx://xxxxx-xxxx.xxx.xxx.xx/xxx/xxxx/xxxxx/xxx/x0.0/xxxxxxxx

xxxxx://xxxxx-xxxx.xxx.xxx.xx/xxx/xxxx/xxxxx/xxx/x0.0/xxxxxxxx/0000/xxxxxxxx xxxxx://xxxxx-xxxx.xxx.xxx.xx/xxx/xxxx/xxxxx/xxx/x0.0/xxxxxxxx/0000/xxxxxx

GKD

xxxxx://xxxxx-xxxx.xxx.xxx.xx/xxx/xxxx/xxxxx/xxx/x0.0/xxxxxx-xxxxxxxxx HHS – YÖS API

xxxxx://xxxxx-xxxx.xxx.xxx.xx/xxx/xxxx/xxx-xxx/x0.0/xxx xxxxx://xxxxx-xxxx.xxx.xxx.xx/xxx/xxxx/xxx-xxx/x0.0/xxx/0000 xxxxx://xxxxx-xxxx.xxx.xxx.xx/xxx/xxxx/xxx-xxx/x0.0/xxx xxxxx://xxxxx-xxxx.xxx.xxx.xx/xxx/xxxx/xxx-xxx/x0.0/xxx/0000

HHS’lerin sağlayacakları API’lerdeki URI çevrimi örnekleri aşağıdaki gibidir.

• xxxxx://xxxxx.xxx.xx/xxx-xxxxxx/xxxxx/xxx/x0.0/xxxxx-xxxx

• xxxxx://xxxxx-xxxx.xxx.xxx.xx/xxx/xxxx/xxxxx/xxx/x0.0/xxxxx-xxxx (BKM API)

• xxxxx://xxxxx.xxx.xx/xxx-xxxxxx/xxxxx/xxx/x0.0/xxxxx-xxxxxxx-xxxxxx

• xxxxx://xxxxx-xxxx.xxx.xxx.xx/xxx/xxxx/xxxxx/xxx/x0.0/xxxxx-xxxxxxx-xxxxxx (XXX API)

• xxxxx://xxxxx.xxx.xx/xxx-xxxxxx/xxxxx/xxx/x0.0/xxxxxxxx

• xxxxx://xxxxx-xxxx.xxx.xxx.xx/xxx/xxxx/xxxxx/xxx/x0.0/xxxxxxxx (BKM API)

• xxxxx://xxxxx.xxx.xx/xxx-xxxxxx/xxxxx/xxx/x0.0/xxxxxxxx/0000

• xxxxx://xxxxx-xxxx.xxx.xxx.xx/xxx/xxxx/xxxxx/xxx/x0.0/xxxxxxxx/0000 (BKM API)

BKM API Geçidi üzerinden yapılan çağrılarda, istek başlığında bulunan “x-aspsp-code” (isteğin iletildiği Hesap Hizmeti Sağlayıcısının kodu) değerine göre HHS API’de standart olarak tanımlanmış olan “basePath” bilgisine servis uzantısı eklenerek HHS’ye yönlendirme yapılır.

Örneğin, istek başlığında xbank’ın kodu varsa, YÖS tarafından yapılan xxxxx://xxxxx-xxxx.xxx.xxx.xx/xxx/xxxx/xxxxx/xxx/x0.0/xxxxx-xxxxxxx-xxxxxx çağrısı BKM API Geçidi tarafından karşılanarak

xxxxx://xxxxx.xxx.xx/xxx-xxxxxx /xxxxx/xxx/x0.0/xxxxx-xxxxxxx-xxxxxx

adresine yönlendirilir.

Bu örnekte, xxxxx://xxxxx.xxx.xx/xxx-xxxxxx basePath bilgisi HHS tarafından HHS API’ye girilen değerdir.

3.6. Karakter Kodlama

API istekleri ve yanıtlarında UTF-8 karakter kodlaması kullanılır. Bu, JSON için varsayılan karakter kodlamasıdır.

Ancak, bir HHS'nin kendi uygulamaları ve ödeme başlattığı ödeme sistemi (FAST vb.) bazı UTF-8 karakterlerini kabul etmeyebilir. HHS, UTF-8 kodlaması içeren bir mesajı işleyemez ve reddederse, HTTP 400 (Hatalı İstek) durum kodu ile yanıt vermelidir.

3.7. Veri Formatı

• Açık bankacılık kapsamındaki zaman damgası, ISO 8601 standartına uygun olarak yerel saat bilgisini ve timezone bilgisini de içerecek şekilde " yyyy-MM-dd’T’HH:mm:ssXXX " formattaki haliyle hazırlanmalıdır.

Örnek: "timestamp": "2021-05-30T20:34:15+03:00"

yyyy : 4 xxxx xxx

MM : Başa ‘0’ eklenmiş, toplam 2 hane ay dd : Başa ‘0’ eklenmiş, toplam 2 hane gün

HH : Başa ‘0’ eklenmiş, toplam 2 hane saat (0-23 arası değer alabilir.)

mm : Başa ‘0’ eklenmiş, toplam 2 hane dakika ss : Başa ‘0’ eklenmiş, toplam 2 hane saniye XXX : ISO 8601 Time zone

• JWT veri paketlerinde kullanılan zaman damgaları, 1 Xxxx 1970 Saat 00:00:00 (UTC) anından itibaren geçen saniye sayısı değerini (Unix Time) kullanır.

• Bir HHS, tarihi yanlış biçimlendirilmiş bir istek aldığında, 400 (Hatalı İstek) durum kodu ve ilgili hata

kodu ile yanıt verir.

• Tüm tutar alanları tam sayı olarak, para birimleri ise ISO4217’deki 3 harfli kodla iletilir. Tutar alanı, tutara ilişkin para biriminin ISO4217’de tanımlı olan tam sayıdan sonraki uzunluğuna göre formatlanarak okunmalıdır. Örneğin 1,20 TRY için tutar alanında “120” değeri iletilir, para birimi TRY olduğu için son iki basamağın kuruş olduğu sonucuna ulaşılacaktır. 12000 Japon Yeni için, ISO4217’de JPY para biriminin ondalık kısmı olmadığından tutar alanında 12000 değeri iletilir.

• Sıralı veri tipleri büyük küçük harfe duyarlıdır.

• Altın para birimi ISO4217’ye uygun biçimde “XAU” cinsinde ve virgülden sonra 2 basamak olacak

şekilde iletilmelidir. Örneğin içerisinde "13,5 gr" altın olan hesap için bakiye 1350 gönderilmelidir.

3.8. İstemci Sertifika Yönetimi

ÖHVPS kapsamında YÖS ve HHS’lerin güvenli bir şekilde tanımlanması amacıyla elektronik sertifikalar kullanılır.

ÖHVPS kapsamında tarafların güvenli bir şekilde tanımlaması, uçtan uca güvenli iletişim, mesaj şifreleme ve mesaj imzalama işlevleri 15/1/2004 tarihli ve 5070 sayılı Elektronik İmza Kanunu’nda açıklanan elektronik sertifikalar kullanılarak sağlanır. Elektronik sertifikada Türkiye Cumhuriyet Merkez Bankası tarafından verilen kuruluş kodu ve kuruluşun türüne dair bilgiler bulunur.

BKM API Geçidi üzerinden yapılan erişimlerde YÖS ve HHS’lere önceden dağıtılmış olan istemci sertifikaları kullanılarak tarafların (sunucu) kimliklerinin doğrulanması sağlanacaktır. İstemci sertifikaları hem test hem de üretim ortamında kullanılacaktır. Sertifikaların işlevselliği ve geçerliliği sertifikasyon sürecinde de sınanacaktır. Söz konusu sertifikaların dağıtım prosedürleri ve kullanımlara yönelik açıklamalar EK-4’te yer verilmiştir.

3.9. Yetkilendirme Türleri

BKM API Geçidi üzerinden yapılan çağrılarda iki temel yetkilendirme türü kullanılır:

1. İstemci Kimlik Bilgileri: Müşteri onayının gerekmediği, sadece YÖS’ün tanımlanıp doğrulandığı API çağrılarında kullanılır. YÖS’ün yetkilendirilmiş olduğu ve faaliyet izninin yaptığı hizmet çağrısına uygun olduğu kontrol edilir. Bu amaçla, YÖS’lere clientId ve clientSecret tahsis edilecektir. YÖS’ler ilgili clientId ve clientSecret ile sadece yetkilendirilmiş oldukları servislere erişebileceklerdir. YÖS’ler kendilerine BKM tarafından sunulacak API’yi, kendi clientID ve clientSecret değerleri ile sorgulayarak “İstemci Kimlik Bilgileri” belirtecini (access token) elde edeceklerdir.

HHS’ler de BKM API geçidi üzerindeki YÖS API’sini sorgulama maksadı ile BKM API Geçidine geldiklerinde, kendilerine atanmış olan clientID ve clientSecret bilgileri ile yetki kontrolleri yapılır.

HHS’ler kendilerinden alınacak username ve password değerleri kullanılarak oluşturulacak basic authentication metodu ile servislerini sunacaklardır.

2. Yetkilendirme Kodu: YÖS’ün doğrulanmasının yanısıra müşterinin GKD ile doğrulanması gereken API çağrılarında kullanılır. Müşteri doğrulanarak yetkilendirme kodu oluşturulması HHS’nin yetkilendirme arayüzüne yönlendirilir. GKD’nin başarıyla tamamlanması sonrasında yetkilendirme kodu YÖS’e dönülür. YÖS daha sonra HHS’nin erişim belirteci (access token) erişim adresini (EK-3:

POST /erisim-belirteci) çağırmak suretiyle yetkilendirme kodunu bir erişim belirteci (access token) ile değiştirerek ilgili kaynakları kullanabilir.

Ödeme emri başlatma ve hesap bilgisi hizmetlerinde hangi yetkilendirme türlerinin kullanılacağı bilgisi, ilgili başlıklardaki erişim adresleri (endpoints) tablolarında yer almaktadır.

erisim-belirteci erisim noktasından elde edilen erisimBelirteci ilişkilendirildiği nesne veya işlem için gönderilen POST isteği başlığında x-access-token alanında iletilir.

Belirli bir süre için tanımlanan erişim belirteci (access token) değerinin yenileme belirteci (refresh token) ile

yenilenmesi gerekir.

Erişim adreslerinde kullanılan yetkilendirme türü ilgili erişim adresi tablolarında belirtilmiştir.

3.10. İstek/Cevap Mesajlarında Kullanılan Nesne Yapıları

İstek ve Cevap mesajlarında kullanılacak olan nesneler tüm elemanlarını kapsayacak şekilde Ek-1 de listelenmiştir. Tüm listelenen elemanlar açısından (Uç nokta mesaj yapılarının belirtildiği tablolarda belirtildiği üzere) alanın Zorunlu (z) veya İsteğe Bağlı (İ) olma durumlarına göre bazı alanlar gönderilebilir veya gönderilmeyebilir.

3.11. Sayfalandırma ve Filtreleme

Sayfalandırma

Çağrıya dönülen kaynak nesnesi içerisindeki kayıtlar bir sayfalandırma yapısı ile çağrılacak şekilde istek oluşturulur.

Oluşturulacak isteğin içerisinde parametreler ile filtreleme, sayfa başına gösterilecek kayıt sayısı ve hangi sayfanın önyüzde gösterileceği bilgileri erişim noktasına iletilir ve ilgili kayıtlar cevap olarak alınır.

Filtreleme

HHS, birden çok kayıt dönülmesi gereken GET çağrılarında sınırlı filtreleme desteği sağlamalıdır. Filtre parametreleri her zaman kaynak nesnesinin belirli alanlarına özgüdür ve nesne için tanımlanan kurallara uymalıdır.

3.12. Mesaj İmzalama

Elektronik imzalar, ÖHVPS API’de gerçekleştirilen işlemlerin ve taşınan verilerin bütünlük ve inkâr edilemezliğini destekler. İmzaların kaynak bazında hangi istek ve yanıtlara uygulandığı belirlidir.

API yalnızca TLS'ye dayanırsa, dijital kayıtları ve inkâr edilemezlik kanıtlarını tutmak zor olur. Bu nedenle, TLS'ye dayanmayan bir inkâr edilemezlik çözümü olarak API isteğinin HTTP başlığında bir JWS kullanılarak sağlanabilir.

HTTP isteğinin gövdesinin hash fonksiyonu (SHA256) ile özeti alınacaktır. Elde edilen özet, asimetrik anahtarları destekleyen bir algoritma kullanılarak imzalanacak ve JWS elde edilecektir.

Bir istek, XXX'xxx özel anahtarı ile imzalanacak ve bu isteğe karşılık gelen yanıt, HHS'nin özel anahtarı tarafından imzalanacaktır.

Tüm API istekleri ve yanıtları imzalanmaz. Xxxxx imzalamanın zorunlu olup olmadığı, desteklenip desteklenmediği her API özelinde belirlenir.

Anahtar Deposu

HHS'ler ve XXX'xxx tarafından güvenilen bir Güven Otoritesi (Trust Anchor), taraflar için bir genel anahtar deposu sağlamaktan sorumludur.

Güven Otoritesi, taraflardan herhangi birisinin oluşturduğu bir anahtar çiftinin açık bölümünü saklayan merkezi bir dizin (BKM tarafından tutulan merkezi kayıt sistemi vb.) olacaktır.

Mesajları doğrulamak için tarafların genel anahtarlarının paylaşılması için BKM bir servis sağlayacaktır. HHS API olarak adlandırılımış olan bu servis ile HHS ve YÖS listelerine ulaşılabildiği gibi doğrulama işlemi için ihtiyaç duyulacak olan genel anahtarlara da bu servis üzerinden erişilebilinecektir.

İlgili Mesaj şifreleme için genel akış, Ek-5 bölümünde detaylarıyla paylaşılmaktadır.

3.13. Durum Kodu

API’ler, iki farklı amaca hizmet eden iki durum kodu kullanır:

• HTTP Durum Kodu, API çağrısının (kaynaktaki HTTP işlemi) sonucunu yansıtır.

• Bazı kaynak payload’larındaki Durum alanı, kaynakların durumunu yansıtır.

3.14. Gereksinimlerinin Sınıflandırılması

Erişim adreslerinin ve alanların kullanımı Zorunlu(Z), İsteğe Bağlı(İ) veya Koşullu(K) olabilir. Kullanımlara ilişkin durumlar ve kullanımın (K) koşullu olduğu duruma ilişkin açıklamalar ilgili tablolarda belirtilmiştir.

İstek ve yanıtta kullanılacak başlık isimleri, ilgili RFC dokümanlarında ve aşağıdaki tabloda yer aldığı şekilde kullanılacaktır. Uygulamaya özelleşmiş başlıklar "X-" ile başlayacaktır. Başlık isimlerinde yer alacak kısaltmalar (örn. PSU, ASPSP gibi) tamamı büyük harfle yazılacak şekilde tanımlanacaktır. Başlık isimleri büyük – küçük harfe duyarlı olmamalıdır. Örneğin x-request-id ya da X-Request-ID olarak gönderilmiş olan bir istek başlığı değişkeni, sunucu tarafında hata vermeyecek şekilde işlenebilmelidir.

3.15. İstek Başlığı

Tablo 2: İstek Başlığında Yer Xxxx Xxxxxxx

Başlık İsimleri

Format

Notlar

POST

GET

DELETE

X-Request-ID

AN1..36

İsteği başlatan YÖS tarafından belirlenen çağrıya özgü talep kimliği. İstek numarası.

Örnek: Ödeme emri başlatma iş akışının her adımda farklı “x-request-id” değeri kullanılır.

Çağrıların aynı yanıtı dönmesinin beklendiği durumlarda (idempotent işlemlerde) aynı değer ile çağrı yapılır.

X-Group-ID

AN1..36

İsteği başlatan YÖS tarafından belirlenen işlem akışına özgü talep kimliği. İşlem grup numarası.

Aynı rıza no’ya ait tüm isteklerde aynı x-group-id bilgisi değeri gönderilmelidir.

Örnek: Ödeme emri başlatma/hesap bilgisi iş akışının her adımında aynı “x-group-id” değeri kullanılır.

Content-Type

AN1..20

Standart HTTP Başlığı; Talepte sağlanan payload’ın biçimini temsil eder:

application/json

(Başka bir değere ayarlanırsa, HHS, 415 Desteklenmeyen Ortam Türü (Unsupported Media Type) ile yanıt vermelidir)

X-ASPSP-Code

AN4

İsteğin iletildiği Hesap Hizmeti Sağlayıcısının kodudur. (Nezdinde ÖH bulunduran kuruluş kodu. Örneğin, Banka, Elektronik Para Kuruluşu ve Ödeme Kuruluşu)

Başlık İsimleri

Format

Notlar

POST

GET

DELETE

X-TPP-Code

AN4

İsteği gönderen Yetkili Ödeme Hizmeti Sağlayıcısı (YÖS) kodudur

PSU-Auth-Date

ISODateTime

ÖHK’nın YÖS üzerinde en son oturum açtığı saat. [RFC7231] Örneğin: auth-date: Tue, 11 Sep 2012 19:43:31 GMT

PSU-IP-Adress

AN7..15

ÖHK YÖS üzerinde oturum açmışsa, işlemi başlattığı cihazın IP adresi.

PSU-IP-Port

AN1..5

ÖHK YÖS üzerinde oturum açmışsa, işlemi başlattığı cihazın Port adresi.

PSU-GEO-

Location

AN1..36

ÖHK’nın işlemi başlattığı cihazın konum bilgisi.

RFC2426 standartına uygun olarak paylaşılmalıdır. Örneğin GEO:"<enlem>,< boylam >

GEO:52.506931,13.144558

PSU-User-Agent

AN 1.. 255

ÖHK’nın işlemi başlattığı cihazın sağladığı user-agent bilgisi. (Tarayıcı, versiyon, işletim sistemi

bilgileri)

PSU-Timestamp

ISODateTime

ÖHK’nın işlemi başlattığı cihazın tarih saat içeren zaman bilgisi.

PSU-Device-ID

AN5..40

ÖHK işlemi mobil uygulama aracılığıyla başlattıysa, kullanılan mobil uygulama ilk yüklendiğinde oluşturulan tekil cihaz veya uygulama belirteci. ÖHK cihazının UUID değeri kullanılabilir.

PSU-Device-Data

AN1..1024

ÖHK’nın işlemi başlattığı mobil cihaza ait veriler. Örnek alanlar:

Başlık İsimleri

Format

Notlar

POST

GET

DELETE

Platform - (Android, iOS, Windows 10 Mobile) Device Model

OS Name OS Version Locale Time zone

PSU-Initiated

AN1

İşlemler servisinde yapılacak sistemsel sorgulardaki işlem limitlerini kontrol amacıyla kullanılır.

İşlemin ÖHK tarafından başlatılması durumunda E , sistem tarafından başlatıldığı durumda H değerini alması beklenir.

Authorization

AN1..4096

YÖS ile BKM API Gateway arasındaki otorizasyon için kullanılan token bilgisidir.

X-Access-Token

AN1..4096

ÖHK’nın GKD sürecinde doğrulanması sonrasında kullanılan erişim simgesi

X-JWS-Signature

AN1..4096

Payload gövdesinin ayrılmış bir JWS imzasını içeren üstbilgi.

Bu başlığın ne zaman belirtilmesi gerektiği hususu ilgili endpoint için belirtilmiştir.

3.16. Yanıt Başlığı

Tablo 3: Yanıt Başlığında Yer Xxxx Xxxxxxx

2 Kullanılan API ve metoda göre kullanılır.

Başlık İsimleri

Format

Notlar

Kullanım

Durumu

X-Request-ID

AN1..36

İsteği başlatan YÖS tarafından belirlenen çağrıya özgü talep kimliği. İstek numarası

İlgili istek başlığındaki bilgi geri dönülür.

X-Group-ID

AN1..36

İsteği başlatan YÖS tarafından belirlenen işlem akışına özgü talep kimliği. İşlem grup numarası.

İlgili istek başlığındaki bu değer geri dönülür.

X-ASPSP-Code

AN4

İsteğin iletildiği Hesap Hizmeti Sağlayıcısının kodudur. (Nezdinde ÖH bulunduran kuruluş kodu. Örneğin, Banka,

Elektronik Para Kuruluşu ve Ödeme Kuruluşu)

X-TPP-Code

AN4

İsteği gönderen Yetkili Ödeme Hizmeti Sağlayıcısı (YÖS) kodudur

Başlık İsimleri

Format

Notlar

Kullanım

Durumu

Content-Type

AN1..20

Standart HTTP Başlığı; Talepte sağlanan payload’ın biçimini temsil eder:

application/json

X-JWS-

Signature

AN1..4096

JWS imzasını içeren üstbilgi.

Bu başlığın hangi yanıtlar için kullanılması gerektiği ilgili endpoint için belirtilmiştir.

Retry-After

AN 1..255

YÖS’ün bir isteği yeniden denemeden önce beklemesi gereken süreyi (saniye cinsinden) gösterir.

HHS, 429 HTTP durum kodu (Too Many Requests) ile döndüğü yanıtların başlığında bu bilgiyi dönmelidir.

x-total-count

N 1..18

Sayfalama kullanıldığı durumda, sorgu sonucu dönecek toplam kayıt sayısı bilgisi yer alır.

Link

1..4096

Sayfalama yapısı kullanıldığında gelen yanıtta birden fazla sayfa var ise; önceki, sonraki, ilk, son sayfalara gitmek için gerekli referanslar link headerında aşağıdaki örnekteki gibi doldurulmalıdır.

İlk sayfada “Önceki” seçeneği olmamalı, son sayfada ise “Sonraki” seçeneği olmamalıdır. Çoklu sayfa yapısı olması durumunda gönderilmesi zorunludur.

Başlık İsimleri

Format

Notlar

Kullanım

Durumu

</ohvps/hbh/s1.0/hesaplar/hspref/islemler?hesapIslemBslTrh=2019-01- 01T00:00:00+03:00&hesapIslemBtsTrh=2023-12- 12T23:59:59+03:00&srlmKrtr=islGrckZaman&srlmYon=Y&syfNo=6&syfKytSayi=100>; rel="next",

</ohvps/hbh/s1.0/hesaplar/hspref/islemler?hesapIslemBslTrh=2019-01- 01T00:00:00+03:00&hesapIslemBtsTrh=2023-12- 12T23:59:59+03:00&srlmKrtr=islGrckZaman&srlmYon=Y&syfNo=4&syfKytSayi=100>; rel="prev",

</ohvps/hbh/s1.0/hesaplar/hspref/islemler?hesapIslemBslTrh=2019-01- 01T00:00:00+03:00&hesapIslemBtsTrh=2023-12- 12T23:59:59+03:00&srlmKrtr=islGrckZaman&srlmYon=Y&syfNo=14&syfKytSayi=100>; rel="last",

</ohvps/hbh/s1.0/hesaplar/hspref/islemler?hesapIslemBslTrh=2019-01- 01T00:00:00+03:00&hesapIslemBtsTrh=2023-12- 12T23:59:59+03:00&srlmKrtr=islGrckZaman&srlmYon=Y&syfNo=0&syfKytSayi=100>; rel="first"

3.17. Idempotency Kuralları

Çağrıların aynı yanıtı dönmesinin beklendiği aşağıdaki durumlarda (idempotent işlemlerde) aynı istek numarası

(x-request-id) değeri ile çağrı yapılır:

• HHS’nin yanıtı kesinti/arıza nedeniyle YÖS’e ulaşmaz ve zaman aşımı söz konusu olursa ya da ÖHK YÖS uygulaması üzerinden çift tıklama ile mükerrer defa HHS API’lerini çağırırsa (API kontrollerinden önce YÖS, çift tıklama kontrolü yapması önerilmektedir.), YÖS aynı istek numarası ile isteği tekrarlamalıdır. HHS, bu durumda, aynı kaynakları (resource) kullanarak daha önce ürettiği yanıtı döner.

• YÖS, yanıt almasına rağmen işleyemeden kaybederse; HHS, bu durumda da, aynı kaynakları (resource) kullanarak daha önce ürettiği yanıtı döner.

• HHS gelen veri gövdesinden CRC32 algoritması ile checksum değeri üretir.

• HHS istek numarası değerini kaydederken, üretilen checksum değerini de kaydetmelidir.

• YÖS aynı istek numarası ve aynı içerik ile yeni bir çağrı yapıldığında, HHS ilk servis çağrım sonucunu döner.

• Ödeme emri post’larında 5 dakika, hesap bilgisi rızası oluşturma post işleminde 5 dakika boyunca HHS’nin aynı istek numarası ve aynı içerik ile gelindiğinde aynı değeri dönmesi beklenir.

• YÖS aynı istek numarası ve HHS tarafından istek gövdesinden üretilecek farklı checksum değeri ile yeni bir çağrı yaptığında; YÖS’ün payload verisinde bir değişiklik olmuş demektir ve HTTP 422 yanıtını dönmesi beklenir.

• Aşağıdaki Public Post işlemleri için bu kural setinin işletilmesi gerekmektedir:

1- Ödeme emri rızası oluşturma

2- Erişim belirteci oluşturma

3- Ödeme emri

4- Hesap bilgisi rızası oluşturma

3.18. HTTP Durum Kodları

RFC 2616'da belirlenmiş olan durum kodları (status code) gönderilen isteğin durumunu YÖS’a standart bir şekilde ifade eder. Eğer bir hata varsa hatayı, gönderilen istek başarılı bir şekilde işlem gördüyse ona ilişkin durumu aktarır. Durum kodları genel olarak 5 kategoridedir.

• 1xx Bilgi

• 2xx Başarılı

• 3xx Yönlendirme

• 4xx İstemci Hatası

• 5xx Sunucu Hatası

Sıralı (Enumarated) Hata Tipleri:

TR.OBHS.Resource

🡺 InvalidFormat

🡺 ConsentMismatch

🡺 NotFound

🡺 InvalidSignature

🡺 MissingSignature

🡺 MethodNotAllowed

🡺 NotAcceptable

🡺 UnsupportedMediaType

🡺 ConsentRevoked XX.XXXX.Xxxxxxxx

🡺 InvalidContent

🡺 InvalidAccount TR.OBHS.Field

🡺 Missing

🡺 Invalid TR.OBHS.Connection

🡺 InvalidCertificate

🡺 ExceededRate

🡺 InvalidTPP

🡺 InvalidASPSP

🡺 InvalidToken

🡺 InvalidTPPRole

TR.OBHS.Server

🡺 InternalError

🡺 ServiceUnavailable

Veri Tipi Örneği:

{

"id": "2b5f0fb2-730b-11e8-adc0-fa7ae01bbebc", "path": "/ohvps/s1.1/obh/odeme-emri-rizasi", "timestamp": "2020-06-13T18:24:38",

"httpCode": 400, "httpMessage": "Bad Request",

"moreInformation": "Resource Schema validation error", "moreInformationTr": "Şema kontrolleri başarısız",

"errorCode": "TR.OBHS.Resource.InvalidFormat",

"fieldErrors": [

{

"objectName": "odemeEmriRizasi",

"field": "kmlkNo",

"messageTr": "boyut '6' ile '30' arasında olmalı",

"message": "size must be between '6' and '30'",

"code": "TR.OBHS.Field.Invalid"

{

"objectName": "odemeEmriRizasi",

"field": "prBrm",

"messageTr": "boş değer olamaz",

"message": "must not be null",

"code": "TR.OBHS.Field.Missing"

}]

}

Veri Tipi Örneği:

Zorunlu header alanlarından biri ya da birkaçı eksik olarak gönderilirse aşağıdaki gibi bir hata dönüşü gerçekleşebilir.

{

"httpCode": "400",

"httpMessage": "Bad Request",

"moreInformation": "One or more required API parameters are missing in the API request."

}

Tablo 4: HTTP Durum Kodları

HTTP Durum

İstek Sonucu ve Açıklamalar

P O S T

G E T

D E L E T E

200 OK

İstek Başarıyla Tamamlandı.

Kaynak güncellemek için yapılan (örneğin, PUT) ve başarıyla tamamlanan isteklerinde kullanılır.

201 Created

İstek Başarılı Oldu.

Kaynak yaratma isteği (örneğin, POST /ödeme-emri-rizasi) başarıyla sonuçlandı.

204 No Content

Silme işlemi başarıyla tamamlandı.

Kaynak silme isteği (örneğin, DELETE /hesap-rizasi/{RizaNo}) başarıyla sonuçlandı.

400 Bad Request

İstekte bozuk, eksik veya uyumlu olmayan JSON gövdesi, URL parametreleri veya başlık alanları var.

İstekle başlatılan işlem yapısal bozukluk, eksik veya tutarsız veri veya HHS tarafındaki kontrollerin hatalı sonuçlanması nedeniyle hata ile sonuçlanır ve hataya ilişkin veriler hata nesnesi içerisinde dönülür:

httpCode: 400

httpMessage: “Bad Request”

moreInformation: “Resource Schema validation error” moreInformationTr: “Şema Kontrolleri Başarısız” errorCode: "TR.OBHS.Resource.InvalidFormat"

fieldErrors:

code: {"TR.OBHS.Field.Invalid", "TR.OBHS.Field.Missing"}

Örn; GET /odeme-emri/22289 çağrısı durumunda 22289 geçerli bir ödeme kaynağı değilse, HHS, 400 koduyla

cevap vermelidir.

{

"id": "2b5f0fb2-730b-11e8-adc0-fa7ae01bbebc", "path": "/ohvps/s1.1/obh/odeme-emri-rizasi", "timestamp": "2020-06-13T18:24:38",

"httpCode": 400, "httpMessage": "Bad Request",

"moreInformation": "Resource Schema validation error", "moreInformationTr": "Şema kontrolleri başarısız", "errorCode": "TR.OBHS.Resource.InvalidFormat",

"fieldErrors": [

{

"objectName": "odemeEmriRizasi", "field": "kmlkNo",

"messageTr": "boyut '6' ile '30' arasında olmalı",

"message": "size must be between '6' and '30'",

"code": "TR.OBHS.Field.Invalid"

{

"objectName": "odemeEmriRizasi", "field": "prBrm",

"messageTr": "boş değer olamaz", "message": "must not be null", "code": "TR.OBHS.Field.Missing"

}

]

}

errorCode: "TR.OBHS.Connection.InvalidTPP" moreInformation: “Invalid TPP Code” moreInformationTr: “Geçersiz Yös Kodu”

errorCode: "TR.OBHS.Connection.InvalidASPSP" moreInformation: “Invalid ASPSP Code” moreInformationTr: “Geçersiz HHS Kodu”

errorCode: "TR.OBHS.Connection. InvalidTPPRole" moreInformation: “Invalid TPP Role” moreInformationTr: “Hatalı Yös Rolü”

401 Unauthorized

Yetkilendirme başlığı eksik, hatalı veya geçersiz olduğundan istek yetkilendirmedi ve erişim

reddedildi.

httpCode: 401

Hataya ilişkin olası sonuç kodları:

errorCode: "TR.OBHS.Connection.InvalidCertificate" moreInformation: “Invalid Certificate” moreInformationTr: “Geçersiz Sertifika”

errorCode: " TR.OBHS.Connection.InvalidCertificate " moreInformation: “Expired Certificate ” moreInformationTr: “SERTIFIKA SURESI DOLMUS”

errorCode: " TR.OBHS.Connection.InvalidCertificate " moreInformation: “Revoked Certificate” moreInformationTr: “SERTIFIKA IPTAL EDILMIS”

Ek olarak, YÖS, süresi dolmuş bir erişim belirteci kullandığında, HHS 401 (Yetkisiz) http kodu ile aşağıdaki hata kodunu dönmelidir.Aşağıdaki nedenlerden herhangi biri nedeniyle bir Erişim Belirtecinin süresi dolduğunda bu durum ortaya çıkabilir:

Rızanın süresi doldu (Son Kullanma Tarihi geçti)

Erişim Belirtecinin şüpheli kullanımı veya sahtekarlık şüphesi Rızada belirlenen gün sayısının aşımı

Bu hata, müşteriden doğru izinlerle yeniden kimlik doğrulaması veya kimlik doğrulaması isteyerek çözülebilir.

errorCode: " TR.OBHS.Connection.InvalidToken " moreInformation: “Invalid Token” moreInformationTr: “Geçersiz Token”

403 Forbidden

Erişim belirtecinin veya rızanın kapsamı uyuşmuyor.

• YÖS bir hesaba/işlem kaynağına erişmeye çalışır ve YÖS, istenen kaynağa erişmek için geçerli izinlere sahip bir rızası yoktur.

Örneğin; hesap bilgisi rızası bakiye izni almamıştır ancak /bakiyeler adresinden istekte bulunmuştur.

httpCode: 403 httpMessage: “Forbidden”

errorCode: "TR.OBHS.Resource.Forbidden" moreInformation: “Insufficient rights”

moreInformationTr: “İzin verilmedi.”

404 Not Found

HHS geçerli bir API erişim adresini sağlamıyorsa, o URL'ye gelen istekler için 404 (Bulunamadı) ile yanıt

vermelidir.

YÖS, uygulama esaslarında tanımlanmayan bir kaynak için bir URL'ye erişmeye çalışırsa (örneğin, GET /yurtdisi- odeme), HHS, 404 (Bulunamadı) ile yanıt vermeyi seçebilir.

httpCode: 404

httpMessage: “Not Found”

errorCode: "TR.OBHS.Resource.NotFound" moreInformation: “Resource not found” moreInformationTr: “Kayıt bulunamadı”

405 Method Not Allowed

YÖS, desteklenmeyen bir yöntemle kaynağa erişmeye çalıştı.

httpCode: 405

httpMessage: “Method Not Found”

errorCode: "TR.OBHS.Resource.MethodNotAllowed" moreInformation: “Method Not Allowed”

moreInformationTr: “İstek yapılan URL için izin verilmeyen metot”

406 Not Acceptable

İstek, geçersiz bir karakter kümesi içeriyor.

httpCode: 406

httpMessage: “Not Acceptable”

errorCode: " TR.OBHS.Resource.NotAcceptable" moreInformation: “Accept Headers not supported” moreInformationTr: “Desteklenmeyen kabul başlıkları”

415 Unsupported Media Type

İstek gövdesi hedef kaynakta bu yöntem tarafından desteklenmeyen bir biçimde oluşturulduğu için işlem reddedildi

httpCode: 415

httpMessage: “Unsupported Media Type”

errorCode: " TR.OBHS.Resource.UnsupportedMediaType" moreInformation: “Content type not supported” moreInformationTr: “Desteklenmeyen içerik tipi”

422 Unprocessable Entity

3.17 Idempotency Kuralları bölümünde örneklenen hata durumu için kullanılır.

httpCode: 422,

httpMessage: "Unprocessable Entity",

moreInformation: "Gönderilen istek başlığı x-request-id değeri ile veri gövdesi sağlama toplamı önceki veri ile uyuşmuyor",

moreInformationTr: "x-request-id header and request checksum does not match with previously sent payload.",

errorCode: "TR.OBHS.Business.InvalidContent"

429 Too Many Requests

Belirli bir süre içinde çok fazla talepte bulunulduğu için işlem reddedildi.

HHS’ler adil kullanım politikalarını aşan talepleri kısıtlayabilir.

httpCode: 429

httpMessage: “Too Many Requests”

errorCode: " TR.OBHS.Connection.ExceededRate"

moreInformation: “The rate limit has been exceeded for the plan or operation being used”

moreInformationTr: “Planda tanımlanmış olan çağrı limiti aşıldı”

500 Internal Server Error

API sunucu / servis katmanında sorun oluştu. İşlem başarısız.

httpCode: 500

httpMessage: “Internal Server Error”

errorCode: "TR.OBHS.Server.InternalError" moreInformation: “Unexpected condition was encountered” moreInformationTr: “Beklenmedik bir durumla karşılaşıldı.”

503 Service Unavailable

Hizmet sürümü kullanımdan kaldırıldı.

Bir API'nin kullanımdan kaldırıldığı ve artık bir HHS tarafından operasyonel olarak desteklenmediği durumlarda, URI yolu hala etkin olabilir ve API isteklerini kabul edebilir. Bu durumda, XXX'xx API sürümünün çevrimdışı olduğunun farkında olması için 503 Hizmet Kullanılamıyor dönmesi önerilir.

httpCode: 503

httpMessage: “Service Unavailable”

errorCode: "TR.OBHS.Server.ServiceUnavailable " moreInformation: “API is currently unable to handle the request” moreInformationTr: “API şu anda isteği işleyemiyor”

3.19. Maskeleme Kuralları

Maskeli olarak iletilmesi gereken verilerin maskeleme kuralları şu şekildedir:

• IBAN verileri Hesap Numarası : İlk 4 ve son 4 karakteri açık, diğer karakterler maskeli olmalıdır. Örnek: TR54******************4812

• Ad-Soyadı / Xxxxxx Xxxxx : Her kelimenin ilk 2 karakteri açık, sonraki karakterler yerine 4 adet ‘*’ karakteri konumlandırılmalıdır.

Örneğin: “FATİH XXXXXX XXXX” ifadesi “FA**** SE**** ER****” şeklinde gösterilmelidir.

• Tabela Unvanı : Her kelimenin ilk 2 karakteri açık, sonraki karakterler yerine 4 adet ‘*’ karakteri konumlandırılmalıdır. Örneğin “BANKALARARASI KART MERKEZİ ANONİM ŞİRKETİ” ifadesi “BA**** KA**** ME**** AN**** Şİ****” şeklinde gösterilmelidir.

• YÖS’ten girilen unvan ve iban bilgileri ödeme emri rızası ve ödeme emri yanıtında açık dönülür, Kolas akışında ödeme emri rızası yanıtı ve ödeme emri istek ve yanıtında maskeli taşınır.

3.20. Fonksiyonel Olmayan Gereksinimler

• HHS’lerin sunuyor oldukları servisleri en fazla 3000 ms içinde yanıt dönecek şekilde tasarlamalıdır.

• YÖS tarafından kullanıcının başlatmadığı otomatize sorgular için aşağıdaki limitler belirlenmiştir.

▪ YÖS, Bireysel ÖHK’lar için hesap bazında günde en fazla 4 adet sorgulama yapabilir.

▪ YÖS, Kurumsal ÖHK’lar için hesap bazında saatte en fazla 12 adet sorgulama yapabilir Diğer taraftan kullanıcının başlattığı Hesap Bilgisi Hizmeti kapsamındaki sorgular HHS

tarafından belirlenen üst rate limitler dahilinde tanımlanabilir.

• HHS’lerin sunuyor oldukları servislere sistemin güvenlik ve sürekliliğini sağlamak adına rate limit koyma ihtiyaçları olur ise, standartlar ve ihtiyaçlara uygun şekilde bir konfigürasyon yapabilirler. Ör: YÖS - Kullanıcı bazında günde X sorgu v.b.

İsteğin kullanıcı tarafından başlatıldığı Request Header içerisinde yer alan Payment Service

User (PSU) alanlarından anlaşılabilir.

• HHS’ler aynı zamanda servislerin ayakta olup olmadığına yönelik olarak bir healthcheck servisi kurmalıdır. HHS’lerin bu servis ile tüm network ve veritabanı ya da servislerinin ihtiyaç duydukları altyapısal erişimleri modellemeli ve bu servisi BKM ile paylaşmaları beklenmektedir. Bu servis düzenli olarak BKM tarafından çağırılarak servislerin ayakta olup olmadıklarının kontrolünün sağlanması planlanmaktadır.

Sunulan her API için /health endpointi ile aşağıdaki bilgileri vermeleri beklenmektedir.

GET /{api ismi}/{versiyon}/health

Örnek:

GET /obh/s1.0/health GET /hbh/s1.0/health

GET /gkd/s1.0/health

HHS ve YÖS API için health servisleri aşağıdaki servislerle kontrol edilebilir. GET /hhs-api/s1.0/health

GET /yos-api/s1.0/health

Başarılı yanıtta Http 200 kodu dönülmelidir. Başarılı Yanıt:

Alan Adı	JSON Alan Adı	Format	Koşullu / İsteğe Bağlı	Açıklama
status	status	AN2..20	Z	“UP”, “DOWN” değerlerini alabilir.

Health servisinden yanıt alınamaması, hata alması ya da status DOWN gelmesi durumunda API Gatewayden istek HHS tarafına iletilmeyecektir.

• OHVPS servisleri ile ilgili olarak HHS’ler, BKM tarafından düzenli olarak sorgulanacaktır, erişilebilirlik ve kullanım oranları takip edilecektir.

• HHS’lerin servislerini erişim yüzdeleri açısından yıl bazında %99.75 oranında ayakta olmalarını sağlayacak şekilde kurgulamaları gerekmektedir.

4. Rıza Durumları

ÖHK, Ödeme Emri Başlatma Hizmetine ya da Hesap Bilgisi Hizmetine müşteri rızasının tesisi ile başlar. ÖHK’nın YÖS uygulaması üzerinden yaptığı işlemler neticesinde rıza durumları değişebilir.

Xxxx’xxx alabileceği durum kodları şu şekilde belirlenmiştir.

B: Xxxxx Xxxxxniyor – İlk rıza talebinde

Y: Yetkilendirildi – Başarılı GKD sonrası yetKod üretildiğinde K: Yetki Kullanıldı – Erişim Belirteci alındığında

E: Yetki ödeme emrine dönüştü – ÖBHS için

S: Yetki Sonlandırıldı

HBHS için : Erişimin Geçerli Olduğu Son Tarih geldiğinde ÖBHS için : Yenileme belirteci Son Tarihi geldiğinde

I :Yetki Iptal

Rıza iptal durumu ise gerek raporlama gerekse müşteri deneyimi perspektifinden doğru bilgilendirmeler yapılabilmesi açısından aşağıdaki gibi detay kodları ile zenginleştirilmiştir:

Xxxx Xxxxx Detay Kodu:

‘01’ : Yeni Xxxx Xxxxxx ile İptal

‘02’ : Kullanıcı İsteği ile HHS üzerinden İptal ‘03’ : Kullanıcı İsteği ile YÖS üzerinden İptal ‘04’ : Süre Aşımı : Yetki Bekleniyor

‘05’ : Süre Aşımı : Xxxxxxxxxxxxxxx

‘00’ : Süre Aşımı : Yetki Ödemeye Dönüşmedi

‘07’ : GKD iptali : Aynı rıza no ile mükerrer çağrımı ‘08’ : GKD iptali : Xxxxxx ile TCKN uyuşmaması

‘09’ : GKD iptali : Uygun ürünü bulunmuyor

‘10’ : GKD iptali : HHS Açık Bankacılık kanalı işleme kapalı ’11’ : GKD iptali : Hesap Yetki Sorunu

‘12’ : GKD iptali : ÖHK HHS müşterisi değil

‘13’ : GKD iptali : ÖHK HHS kontrollerini aşamadı ‘14’ : GKD iptali : Başarısız GKD

‘15’ : GKD iptali : ÖHK isteği ile XXX’xxx xxxxxxxxxx ‘00’ : GKD iptali : Diğer

4.1 ve 4.2 bölümlerinde detaylandırılan rıza durum değişikliklerinde statü kodları kullanılmıştır.

Örneğin B🡪 I/01 denildiğinde “Yetki Bekleniyor” statüsünden “Yetki İptal” statüsüne Rıza Iptal Detay Kodu da ‘01’ yani ‘Yeni Xxxx Xxxxxx ile İptal’ olarak güncellenmelidir ifade edilmiştir.

ÖHK verdiği rıza sırasında seçtiği hesaplarından biri kapatılırsa, diğer hesaplara ait bilgileri görmeye devam eder. Ancak XXX’xxx hesabına ait bilgilerinin YÖS'e iletilmesini istemediği durumda, rızasını tamamen iptal ederek yeni hesap listesi ile yeni rıza vermesi gerekmektedir. Yani hesap kapanması nedeniyle rıza geçerliliğini yitirmez. Müşterinin proaktif olarak bu hesabı rızadan çıkarması durumunda rıza iptali olur.

Rıza iptal edilmediği ve geçerli olduğu sürece kapalı hesaplar için diğer çevrimiçi kanallarda uygulanan yöntem izlenmelidir. Diğer çevrimiçi kanallarda kapalı hesaplara ilişkin bilgi dönülmüyor ise ÖHVPS'den de dönüş yapılmaz. ÖHK’nın rıza onayı verdiği açık hesaplarının tümü HHS tarafında kapatıldığı durumda, yine aynı şekilde HHS çevrimiçi kanallarında koyduğu kurallara göre bu hesaplarının YÖS uygulamasında gösterilmesine karar verir.

Hesap kapama ve ticari kullanıcıların hesaplar üzerindeki yetki değişiklikleri HHS'nin iç sistemleri tarafından yapılan kontrollerle yönetilir. Buradaki değişiklikler ile HHS sistemsel olarak rıza iptali gerçekleştiremez.

Müşteri izni ve onayı dahilinde rıza iptal gerçekleştirilmesi gerekmektedir.

4.1. Hesap Bilgisi Hizmeti Rıza durum değişiklikleri

Kural: 1 ÖHK'nın 1 YÖS için 1HHS'de Y, K, B statüsünde 1 rızası olabilir.

Bir ÖHK hem kişisel olarak hem de bir kurumun kullanıcısı olabilir. Bu durumda kurum ve kişisel rıza aynı anda mevcut olabilmelidir. Xxxx xxxxxxxxx, HHS tarafından uygun şekilde yönetilmelidir.

1. Hesap Bilgisi Rızası isteği HHS’ye iletilir.

a. HHS müşteriye ait içeride rıza var mı kontrol eder. Eğer yoksa RIZA = B Yetki Bekleniyor tipinde

yeni rıza no oluşturur.

b. Eğer içeride rıza varsa

i. Rıza tipi Yetki Bekleniyor (B) ise

HHS, sistemde Yetki Bekleniyor (B) statüsünde kayıt olduğu için,

öncelikle eski kaydı Iptal(I) statüsüne getirir. Xxxx Xxxxx Detay Kodu “Yeni Xxxx Xxxxxx ile iptal” olmalıdır. B 🡪 I / 01

Sonrasında, Yetki Bekleniyor (B) statüsünde yeni rıza oluşturur.

ii. Xxxx Xxxx Yetkilendirildi (Y) ve Yetki Kullanıldı (K) ise

Müşterinin halihazırda verilmiş bir rızası vardır. HHS, önce rıza iptali yapılmasına dair hata döner.

TR.OBHS.Resource.ConsentMismatch

iii. Rıza tipi Yetki Sonlandırıldı(S) ise Yetki Bekleniyor (B) tipinde yeni rıza no oluşturur.

iv. Rıza tipi Iptal (I) ise Yetki Bekleniyor (B) tipinde yeni rıza no oluşturur.

2. GKD başarılı bir şekilde tamamlandığında Rıza durumu Yetki Bekleniyor’dan Yetkilendirildi’ye güncellenir. B 🡪 Y

GKD'nin gerçekleşmediği durumlardan HHS haberdar olmayabilir.

• Müşteri GKD yapmadan ayrılmış olabilir. (ÖR: Tarayıcıyı kapatmış olabilir)

Rıza Yetki Bekleniyor (B) statüsünde kalır. 5 dakika içerisinde sistem tarafından Yetki Bekleniyor (B) statüsündeki kayıtlar Yetki İptal : Yetki Bekleniyor Süre Aşımı olarak güncellenir. B 🡪 I / 04 Bkz. 9. Madde.

GKD'nin gerçekleşmediği durumlardan HHS haberdardır. HHS yonlendirme adresinin query

parametrelerine rizaIptDtyKod değerini ekleyerek bu durumu YÖS’e bildirmek zorundadır.

• Aynı rızano ile mükerrer çağrım yapılmıştır. Yetki Bekleniyor 🡪 Yetki Iptal B 🡪 I / 07

• Rızano ile TCKN uyuşmazlığı. Yetki Bekleniyor 🡪 Yetki Iptal B 🡪 I / 08

• ÖHK'nın HHS'de ilgili ürününün olmadığı durum (hesap/kart) Yetki Bekleniyor 🡪 Yetki Iptal B 🡪I / 09

• Açık bankacılık kanalınız işleme kapalıdır. Yetki Bekleniyor 🡪Yetki Iptal B 🡪I / 10

• Kullanıcının HHS'deki hesaplarında yeterli yetkisinin olmama durumu Yetki Bekleniyor

🡪Yetki Iptal B 🡪I / 11

• ÖHK'nın ilgili HHS müşterisi olmadığı durum Yetki Bekleniyor 🡪Yetki Iptal B🡪I / 12

• HHS’nin ÖHK için yaptığı kontrollerin başarısız olduğu durum Yetki Bekleniyor 🡪Yetki Iptal B 🡪 I / 13

• Müşteri kendini doğrulayamamış olabilir. Başarısız GKD Yetki Bekleniyor 🡪Yetki Iptal B 🡪 I / 14

• ÖHK GKD yapmadan ayrılmış olabilir. HHS'nin haberinin olduğu durum (Ör: HHS ekranında yer alan VAZGEÇ butonuna basmış olabilir.) Yetki Bekleniyor 🡪Yetki Iptal B 🡪 I / 15

• Diğer Yetki Bekleniyor 🡪Yetki Iptal B 🡪 I / 16

GKD gerçekleşti ve rıza durumu Yetki bekleniyor harici bir statüde iken, YÖS tekrar GKD yapılması için HHS’ye yönlendirir ise HHS uygun bir hata mesajı ile işlemi sonlandırmalıdır. Burada verilen hata YÖS’e iletilemeyecektir. Bu durum yetkod parametresinin YÖS’e iletilemediği durumda ya da farklı bir şekilde gerçekleşmiş olabilir.

3. Müşteri hesaplarında/izin türlerinde/Erişimin Geçerli Olduğu Son Tarih bilgilerinden bir ya da birden fazlasında güncelleme yapmak için YÖS ekranına girer.

a. YÖS önce Xxxx Xxxxx API'sini çağırır. Sonra yeni değerlerle yeni bir rıza isteğinde bulunur. Tekrar

GKD gerekir.

b. YÖS rıza iptal yapmadan yeni rıza alma akışına başlarsa 1.b akışı devreye girer.

c. Xxxx xxxxxxleme ilerleyen sürümlerde ele alınacaktır.

4. Erişim Belirteci API çağrımı yapıldığında; HHS, rıza numarasının Y - Yetkilendirildi statüsünde olduğunu kontrol etmelidir. Y statüsünde ise erişim belirteci tahsis edilir.

Y statüsünde değil ise TR.OBHS.Resource.ConsentMismatch hatası verilmelidir. Erişim belirteci alındığında rıza durumu K: Yetki Kullanıldı yapılır. Y🡪K

5. Sorgulama: HBHS, rıza alma akışına başlamadan önce, daha önce oluşturulmuş bir hesap bilgisi-rizasi kaynağının durumunu, isteğe bağlı olarak alabilir. Rıza numarası ile sorgulama yapılır.

6. Hesap Bilgisi Rızasının İptali: HBHS üzerinden ya da HHS üzerinden yapılan rıza iptallerinde Rıza statüsü İptal Edildi olarak güncellenir. Rıza numarası ile iptal sağlanır.

a. HHS üzerinden rıza iptali yapmış olabilir. Rıza durumu sorgulanır.

Rıza numarası B- Yetki Bekleniyor ve Y-Yetkilendirildi ve K Kullanıldı statüsüne sahip ise iptal statüsüne getirilir. Xxxx xxxxxxx timestamp ile güncellenir.

HHS, Rıza iptalinde aynı zamanda erişim belirtecini de invalid hale getirmelidir.

B 🡪 I / 02 Y 🡪 I / 02 K 🡪 I / 02

b. YÖS üzerinden yapılacak iptal işleminde yine Y ve B ve K statüsünde ise iptal edilebilir.

B 🡪 I / 03 Y 🡪 I / 03 K 🡪 I / 03

Rıza numarası Yetki Sonlandırıldı (S) statüsüne sahip ise iptal gerçekleşmez. “Rıza'nız iptal edilebilecek statüde değildir.” hatası müşteriye yansıtılır. TR.OBHS.Resource.ConsentMismatch

7. ÖHK’nın verdiği rıza süresi dolmuş olabilir.

Erişimin Geçerli Olduğu Son Tarih geldiğinde Rıza durumu Yetki Kullanıldı’dan Yetki Sonlandırıldı durumuna çekilmelidir. K 🡪 S

8. Hesaplar, Bakiye ve işlemler servislerinde rıza kontrolü ile işleme başlanmalıdır. Rıza durumu "K: Yetki Kullanıldı" dışındaki statülerde işleme devam edilmemelidir. Bu durumda aşağıdaki hata iletilmelidir:

TR.OBHS.Resource.ConsentMismatch

YÖS bu servisleri çağırırken ÖHK rızası iptal statüsünde ise bu iptal HHS üzerinden yapılmış olabilir. (YÖS kendi uygulamasından iptal akışını gerçekleştirdiğinde, yeni rıza alarak işlemlere başlayacağı düşünülmektedir. Ancak yine de YÖS tarafından sorgulama yapılırsa ConsentRevoked hatası HHS’den dönmelidir.) Rıza durumu Iptal ve Rıza Iptal Detay Kodu 2 ise YÖS’ün HHS’ üzerinden yapılmış İptal’den haberdar olabilmesi için aşağıdaki hata kodu iletilmelidir:

TR.OBHS.Resource.ConsentRevoked

Rıza sorgulama, Rıza iptal API'lerinde ilgili rıza kaydı bulunamaz veya sorgulayan kurumun yetkisi yoksa (örn : YÖS’ün farklı bir YÖS’e ait rıza noyu sorgulaması)

TR.OBHS.Resource.NotFound hatası verilmelidir.

9. HHS/YÖS tarafında rıza bilgileri belirli aralıklarla sistem kullanıcısı tarafından taranır:

5 dakikadan uzun süredir “Yetki Bekleniyor” statüsünde kalan kayıtların statüleri güncellenir.

Yetki Bekleniyor 🡪 Xxxx Xxxxx / Süre Aşımı : Yetki Bekleniyor B 🡪 I / 04

5 dakikadan uzun süredir “Yetkilendirildi” statüsünde kalan kayıtlar statüleri güncellenir.

Yetkilendirildi 🡪 Xxxx Xxxxx / Süre Aşımı: Yetkilendirildi B 🡪 I / 05

Yukarıda bahsedilen, YÖS Süre Aşımı nedeniyle rıza iptal statüsü güncellemelerini yapmadan önce HHS’yi sorgulayarak rıza durumunu öğrenmeli ve süre aşımı dışında bir kodu varsa aynı kodla kendi sistemini güncellemelidir.

Erişimin Geçerli Olduğu Son Tarih geldiğinde rıza statüsü Yetki Kullanıldı’dan Yetki Sonlandırıldı’ya güncellenir. K 🡪 S

4.2. Ödeme Bilgisi Hizmeti Rıza Durum Değişiklikleri

Kural: 1 ÖHK'nın 1 YÖS için 1HHS'de istediği kadar rızası olabilir.

Kurum ve kişisel rıza aynı anda mevcut olabilmelidir. Xxxx xxxxxxxxx, HHS tarafından uygun şekilde yönetilmelidir.

1. Ödeme Emri Rızası isteği HHS’ye iletilir. İçeride rıza olup olmamasına bakılmaksızın Yetki Bekleniyor

(B) tipinde yeni rıza no oluşturur.

2. GKD başarılı bir şekilde tamamlandığında Rıza durumu Yetki Bekleniyor’dan Yetkilendirildi’ye güncellenir.

B 🡪 Y

GKD'nin gerçekleşmediği durumlardan HHS haberdar olmayabilir.

• Müşteri GKD yapmadan ayrılmış olabilir. (ÖR: Browserı kapatmış olabilir)

Xxxx Xxxxx Xxxxxniyor (B) statüsünde kalır. 5 dakika içerisinde sistem tarafından Yetki Bekleniyor (B) statüsündeki kayıtlar Xxxx Xxxxx :Yetki Bekleniyor Süre Aşımı olarak güncellenir. Bkz. 9. Madde.

GKD'nin gerçekleşmediği durumlardan HHS haberdardır. HHS yonlendirme adresinin query

parametrelerine rizaIptDtyKod değerini ekleyerek bu durumu YÖS’e bildirmek zorundadır.

• Aynı rızano ile mükerrer çağrım yapılmıştır. Yetki Bekleniyor 🡪 Yetki Iptal B 🡪 I / 07

• Rızano ile TCKN uyuşmazlığı. Yetki Bekleniyor 🡪 Yetki Iptal B 🡪 I / 08

• ÖHK'nın HHS'de ilgili ürününün olmadığı durum (hesap/kart) Yetki Bekleniyor 🡪 Yetki Iptal B

🡪I / 09

• Açık bankacılık kanalınız işleme kapalıdır. Yetki Bekleniyor 🡪Yetki Iptal B 🡪I / 10

• Kullanıcının HHS'deki hesaplarında yeterli yetkisinin olmama durumu Yetki Bekleniyor

🡪Yetki Iptal B 🡪I / 11

• ÖHK'nın ilgili HHS müşterisi olmadığı durum Yetki Bekleniyor 🡪Yetki Iptal B🡪I / 12

• HHS’nin ÖHK için yaptığı kontrollerin başarısız olduğu durum Yetki Bekleniyor 🡪Yetki Iptal B

🡪 I / 13

• Müşteri kendini doğrulayamamış olabilir. Başarısız GKD Yetki Bekleniyor 🡪Yetki Iptal B

🡪 I / 14

• ÖHK GKD yapmadan ayrılmış olabilir. HHS'nin haberinin olduğu durum (Ör: HHS ekranında yer alan VAZGEÇ butonuna basmış olabilir. ) Yetki Bekleniyor 🡪Yetki Iptal

B 🡪 I / 15

• Diğer Yetki Bekleniyor 🡪Yetki Iptal B 🡪 I / 16

3. GKD muafiyeti olduğunda YÖS HHS’den arka planda onay alır. Bu onay sırasında rıza durumu

Yetkilendirildi yapılır. B 🡪 Y

4. Erişim Belirteci API çağrımı yapıldığında; HHS, rıza numarasının Y - Yetkilendirildi statüsünde olduğunu

kontrol etmelidir. Y statüsünde ise erişim belirteci tahsis edilir.

Y statüsünde değil ise TR.OBHS.Resource.ConsentMismatch hatası verilmelidir. Erişim belirteci alındığında rıza durumu K: Yetki Kullanıldı yapılır. Y🡪K

5. Ödeme Başlatma API rıza kontolü ile işleme başlamalıdır.

Rıza durumu "K: Yetki Kullanıldı” dışındakiler için işleme devam edememelidir. Bu durumda aşağıdaki

xxxx iletilmelidir: TR.OBHS.Resource.ConsentMismatch

Eğer rıza iptal statüsünde ise YÖS’ün haberi olması için bir hata kodu dönülür.

TR.OBHS.Resource.ConsentRevoked

6. Sorgulama: GKD işleminin başarıyla tamamlanıp Ödeme Emri Rızasının yetkilendirilmesi esnasında, gönderen hesap seçiminin HHS ekranında yapıldığı durumlarda, ödeme emri isteğinde gönderen hesap bilgileri alanının zorunlu olması nedeniyle, ödemeEmriRizasi nesnesi sorgulanarak gönderen hesap bilgileri (hesap numarası ve/veya hesap referansı) alınmalıdır.

Rıza sorgulama, Ödeme Emri Sorgulama API'lerinde ilgili rıza kaydı bulunamaz veya sorgulayan kurumun yetkisi yoksa (örn : YÖS’ün farklı bir YÖS’e ait rıza noyu sorgulaması)

TR.OBHS.Resource.NotFound hatası verilmelidir.

7. Ödeme Emri Rızasının İptali bulunmamaktadır.

8. Ödeme Emri gerçekleştiğinde K: Yetki Kullanıldı Statüsü E: Yetki ödeme emrine dönüştü ye döner. K🡪E

9. HHS/YÖS tarafında rıza bilgileri belirli aralıklarla sistem kullanıcısı tarafından taranır:

5 dakikadan uzun süredir “Yetki Bekleniyor” statüsünde kalan kayıtların statüleri güncellenir.

Yetki Bekleniyor 🡪 Xxxx Xxxxx / Süre Aşımı : Yetki Bekleniyor B 🡪 I / 04

5 dakikadan uzun süredir “Yetkilendirildi” statüsünde kalan kayıtlar statüleri güncellenir.

Yetkilendirildi 🡪 Xxxx Xxxxx / Süre Aşımı : Yetkilendirildi B 🡪 I / 05

5 dakikadan uzun süredir “Yetki kullanıldı” statüsünde kalan kayıtlar statüleri güncellenir.

Yetki kullanıldı 🡪 Xxxx Xxxxx / Süre Aşımı : Yetki Ödemeye Dönüşmedi B 🡪 I / 06

Yenileme belirteci Son Tarih geldiğinde rıza statüsü Yetki ödeme emrine dönüştü’den Yetki Sonlandırıldı ya güncellenir. E 🡪 S

10. GKD muafiyeti sadece ödeme başlatma servislerinde bulunmaktadır.

5. Güçlü Kimlik Doğrulama

Müşteri için güçlü kimlik doğrulama, ÖHK’nın (müşterinin) kimliğinin doğrulamada kullanılan ve bir bileşenin ele geçirilmesinin diğer bileşenin güvenliğini tehlikeye atmayacağı en az iki bileşenden oluşan, bu iki bileşenin de müşterinin “bildiği”, “sahip olduğu” veya “biyometrik bir karakteristiği olan” bileşen sınıflarından farklı ikisine ait olacak şekilde seçildiği yöntemi tanımlar.

Ödeme ve Elektronik Para Kuruluşlarının Bilgi Sistemleri ile Ödeme Hizmeti Sağlayıcılarının Ödeme Hizmetleri Alanındaki Veri Paylaşım Servislerine İlişkin Tebliğ uyarınca hesap bilgisi hizmetinde müşterinin onayının alınması esnasında ve ödeme emri başlatma hizmetinde her bir ödeme emri başlatma işleminde HHS tarafından müşteriye güçlü kimlik doğrulama (GKD) uygulanması esastır. Buna göre:

1. Hesap bilgisi hizmetinde ÖHK’nın onayının alınması esnasında Tebliğin 26 ncı maddesinin 1 inci fıkrası uyarınca HHS tarafından ÖHK’ya GKD uygulanır.

2. Ödeme emri başlatma hizmetinde, Tebliğin 26 ncı maddesinin 2 nci fıkrası uyarınca HHS tarafından ÖHK’ya güçlü kimlik doğrulama uygulanır ve işlem doğrulama kodu ile ÖHK’nın onayı alınır.

3. Ödeme emri başlatma hizmetinde, Tebliğin 26 ncı maddesinin 3 nci fıkrası uyarınca HHS tarafından ÖHK’ya güçlü kimlik doğrulama uygulanmasına ilişkin istisna veya ilave güvenlik önlemleri işbu API İlke ve Kuralları belgesinde tanımlanır.

4. HHS, güçlü kimlik doğrulama sürecinde ÖHK’nin sahip olduğu bileşen sınıfı olarak SMS OTP ya da

SMS ile işlem doğrulama kodu kullanabilir.

5. HHS, aşağıdaki hallerde veya Tebliğin 10 uncu maddesinin ikinci fıkrasında belirtilen risk

değerlendirmesi sonucuna göre tek bileşen ile kimlik doğrulama yapabilir.

• Ödemenin göndereni ve alıcısının aynı olması,

• Daha önce tanımlanmış güvenli alıcılar listesine ödeme yapılması,

• ÖHK’nin talimatına istinaden gerçekleştirilen düzenli bir ödeme olması.

6. Tek bileşen ile kimlik doğrulama yapılan bu işlemlerle ilgili olarak gerçekleştirilen işlemin müşteri tarafından yapıldığını ispat etme yükümlülüğü HHS’ye ait olur.

7. İşlem Doğrulamada Tebliğin 3 üncü maddesinin birinci fıkrası ğğ bendindeki işlem bilgisi tanımına uygun olarak aşağıdaki bilgiler ile Tebliğin 3 üncü maddesinin birinci fıkrası hh bendinde tanımlanan işleme özel üretilmiş işlem doğrulama kodu birlikte kullanılır.

• Alıcı Unvan (Kolas akışında maskeli olarak) (ödeme emri başlatma hizmeti)

• Tutar (ödeme emri başlatma hizmeti)

• Referans bilgisi (8 karakterden küçük ise alanın tüm değeri, büyük ise ilk 4 ve son 4 hanesi) İşleme ait yukarıdaki bilgilerden en az biri değiştiği zaman Tebliğin 3 üncü maddesinin birinci fıkrası hh bendinde belirtildiği gibi yeni bir işlem doğrulama kodu üretilecek şekilde akış kurgulanmalıdır.

8. İşlem doğrulama kodunun gönderilmesinden HHS sorumludur. HHS, Tebliğin 10 uncu maddesinin ikinci fıkrasında belirtilen risk değerlendirmesi sonucuna göre işlem doğrulama kodu kullanmaksızın ÖHK’nın onayını alabilir. İşlem doğrulama kodu kullanılmayan işlemlerle ilgili olarak gerçekleştirilen işlemin ÖHK tarafından yapıldığını ispat etme yükümlülüğü HHS’ye aittir.

9. ÖHVPS API standartı kapsamında iki adet Güçlü Kimlik Doğrulama (GKD) yöntemi kullanılacaktır:

• Yönlendirmeli (Redirect) GKD Yöntemi

• Ayrık (Decoupled) GKD Yöntemi

10. HHS asgari olarak tarayıcı tabanlı Yönlendirmeli GKD yöntemini desteklemek zorundadır.

11. Çerçeve sözleşme kapsamında olmayan tek seferlik ödeme işlemleri sadece Yönlendirmeli GKD yöntemi ile gerçekleştirilebilir.

5.1. Yönlendirmeli Güçlü Kimlik Doğrulama

Yönlendirmeli GKD Yönteminde, müşteri kimlik doğrulama için YÖS tarafından HHS arayüzüne yönlendirilir.

Müşteri HHS’ye (uygulama veya web arayüzü vasıtasıyla) yönlendirildikten sonra müşterinin güçlü kimlik doğrulaması adım adım ve doğrudan HHS ile müşteri arasında yürütülür. GKD’nin tamamlanmasından sonra müşteri tekrar YÖS uygulamasına yönlendirilir.

Yönlendirmeli GKD Yöntemi için üst düzey örnek iş akışı aşağıdaki adımlardan oluşur:

1. YÖS, GKD için HHS tarafından tanımlanan arayüze (tarayıcı ya da uygulama) yönlendirme yapar.

2. Müşteri, YÖS arayüzünden ayrılır, yönlendirildiği HHS arayüzü üzerinde kimlik doğrulama işlemlerini gerçekleştirir.

3. GKD tamamlandıktan sonra müşteri, YÖS arayüzüne tekrar yönlendirilir ve işlem sonucu görüntülenir.

Yönlendirmeli GKD için temel gereklilikler şunlardır:

• Ödeme hizmeti (hesap bilgisi veya ödeme emri başlatma hizmeti) tarayıcı ya da uygulama tabanlı bir şekilde sunulabilir. Bu nedenle, YÖS ve HHS’lerin Yönlendirmeli GKD için asgari olarak tarayıcı tabanlı yönlendirme akışını desteklemeleri gerekmektedir.

• Çerçeve sözleşme (ÇS) kapsamında olmayan tek seferlik ödeme işlemleri sadece Yönlendirmeli GKD yöntemi ile gerçekleştirilebilir.

Xxxxyıcı Tabanlı Yönlendirme

HHS’nin web arayüzüne,

• HHS’nin mobil uygulamasının olmadığı,

• ÖHK’nın ödeme hizmetini (hesap bilgisi veya ödeme emri başlatma hizmeti) sunduğu mobil cihazda HHS uygulamasının yüklü olmadığı,

durumlarda yönlendirme yapılır.

YÖS’ün mobil uygulaması varsa mobil cihazda uygulamadan tarayıcıya, YÖS’ün mobil uygulaması yoksa ödeme hizmetinin sunduğu cihazda (Kişisel Bilgisayar veya Mobil Cihaz) tarayıcı üzerinden yönlendirme yapılır.

Uygulama Tabanlı Yönlendirme

ÖHK’nın ödeme hizmetini (hesap bilgisi veya ödeme emri başlatma hizmeti) YÖS’ün mobil uygulaması ile kullanıyorsa, aynı mobil cihazda HHS’nin mobil uygulamasının yüklenmiş olması durumunda, ÖHK doğrulamasının HHS mobil uygulaması tarafından yapılması için uygulama tabanlı yönlendirme yapılır. Böylece ÖHK, ödeme hizmetine erişim için HHS’nin mobil kanalına erişim sırasında kullandığı doğrulama yöntemini ile doğrulanabilir.

Tablo 5: Yönlendirmeli Güçlü Kimlik Doğrulama Kanalları

Doğrulama Yöntemi

YÖS Olası Ortam

HHS Olası Ortam

Tarayıcı Tabanlı Yönlendirme

Kişisel Bilgisayar (masaüstü, dizüstü) / Mobil Cihaz

Kişisel Bilgisayar (masaüstü, dizüstü) /

Mobil Cihaz

Uygulama Tabanlı Yönlendirme

Mobil Cihaz

5.2. Ayrık Güçlü Kimlik Doğrulama

Ayrık GKD Yöntemi iş akışı, Yönlendirmeli GKD Yönteminin işlem akışına benzer. Fark, HHS'nin, çevrimiçi arayüzünden bağımsız olan herhangi bir uygulama veya cihaz aracılığıyla ödeme işlemi ayrıntılarını içeren bir anlık bildirim (push notification) göndererek müşteriden kimlik doğrulaması istemesidir. Ayrık GKD Yöntemine dayalı bir işlem için (çok basitleştirilmiş) üst düzey örnek bilgi akışı şu şekildedir:

1. Müşteri, YÖS arayüzünde işlemini başlatır.

2. YÖS, talebini müşteriye ait TCKN, VKN, YKN gibi tekil tanımlayıcı kimlik numarası bilgisi içerecek şekilde HHS’ye iletilir.

3. HHS tekil tanımlayıcı bilgisini kullanarak farklı bir cihaz veya uygulama üzerinden müşteriye anlık bildirim gönderir ve doğrulama yapılmasını sağlar. Bu şekilde HHS kendi mobil uygulamasına erişim için kullanılan doğrulama yöntemini aynen kullanabilecektir.

4. YÖS, herhangi bir yere yönlendirme yapmadan işlemin sonucunu bekler, müşteri YÖS arayüzünden ayrılmaz (arayüz aynı kalır).

5. Kimlik doğrulama sonrası, YÖS arayüzünde işlem sonucu görüntülenir.

5.3. Yönlendirme/Bildirim Adresleri ve Durum Kodu Parametresi

CSRF Ataklarından korunmak için ve YÖS uygulamasının bir önceki durumunu restore edebilmesi için; YÖS tarafından iletilen yönlendirme ve bildirim adreslerine , Oauth2 standartlarındaki state parametresine eşdeğer, durum kodu (drmKod) parametresinin eklenmesi gerekmektedir. Durum kodu parametresi YÖS tarafından üretilen, tekil ve kolay tahmin edilemeyen bir değer olmalıdır. Rıza isteği gönderimi aşamasında oluşturulmalıdır. YÖS uygulamasında uygun bir yerde saklanmalıdır (cookie, session, local storage gibi) .

Durum kodu, rıza isteğindeki yönlendirme adresine parametre olarak eklenir. GKD süreci sonrasında yetki kodu ile birlikte bu bilgi, HHS tarafından YÖS’e iletilir. YÖS sakladığı değer ile parametre olarak gelen değerin eşitliğini kontrol eder. Aynı ise erişim belirteci almak üzere akışı ilerletir. Farklı ise işlemi keser.

5.4 Healthcheck API

GET /health

HHS’lerin sunacağı bu servis, düzenli olarak BKM tarafından çağırılarak servislerin ayakta olup olmadıklarının kontrolünün sağlanması planlanmaktadır.

Başarılı yanıtta Http 200 kodu dönülmelidir. Başarılı Yanıt:

Alan Adı	JSON Alan Adı	Format	Koşullu / İsteğe Bağlı	Açıklama
status	status	AN2..20	Z	“UP”, “DOWN” değerlerini alabilir.

5.5 Güçlü Kimlik Doğrulama Kontrolleri

ÖHK, GKD için HHS uygulamasına yönlendirildiğinde, HHS’nin çeşitli kontroller yaparak işlemin doğruluğunu teyit etmesi gerekmektedir. Yapılması gereken kontrollere ait temel senaryolar aşağıdaki tabloda belirtilmiştir. Bu senaryolar baz alınarak HHS’ler tarafından zenginleştirilebilir.

Zorunlu olarak belirtilen hata durumlarının HHS’ler tarafından gerçeklenmesini ve uygun hata kodlarının YÖS’e iletilmesi; ileride oluşabilecek mutabakatlaşma sorunlarını ortadan kaldırabilecek, yapılacak raporlamalar kapsamında sistem ve süreç iyileştirmelerine katkı sağlayacak, son kullanıcı açısından da alınan hataya yönelik bilgilendirici içerik sağlayacaktır.

Hata açıklamaları; hata koduna uygun ya da uyumlu olmak kaydıyla, HHS ve XXX tarafından farklı şekillerde

sunulabilir.

GKD Sırasında yapılması gereken kontroller

Rıza İptal

Detay Kodu

HHS hata

açıklaması*

Yös ekranında listelenecek örnek mesaj metni*

Örnek Senaryo

Zorunlu / Opsiyone l

Rıza durumunun "Yetki Bekleniyor" olmadığı durum

Yetki Hatası

ÖHK, GKD işlemi tamamlandıktan sonra YÖS ekranında ileri- geri yaparak ya da ÖHK'nın yönlendirme adresini kopyalayarak tarayıcıya yapıştırması ile tekrar HHS'ye yönlendirir. Bu durumda HHS bu hata mesajını iletir.

Zorunlu

Xxxxxx ile kimlik bilgileri uyuşmazlığı.

İşleminiz gerçekleştirileme miştir.

YÖS tarafından başlatılan rıza içerisinde yer alan kimlik bilgisi (TCKN) ile HHS'de GKD yapılan ÖHK'nın bilgilerinin uyuşmadığı durumda

Zorunlu

ÖHK'nın HHS'de ilgili ürününün olmadığı durum (hesap/kart)

Gösterilebilecek hesap/kart bulunamamıştır.

ÖHK'nın uygun statülü hesabının olmadığı durumda

Zorunlu

Açık bankacılık kanalınız işleme kapalıdır.

Açık bankacılığı ayrı bir kanal olarak tanımlamış HHS'lerde, ÖHK'nın işlemlerini AB kanalına kapatması durumunda

Opsiyonel

Kullanıcının HHS'deki hesaplarında yeterli yetkisinin olmama durumu

Yetkiniz

bulunmamaktadır

1- Kurumsal firma kullanıcılarının hesaplar üzerinde işlem yetkisinin olmaması durumunda

2- Bireysel ortak hesaplarda hesap kısıtı bulunuyorsa (para çıkışına izin verilmediği durum)

Zorunlu

ÖHK'nın ilgili HHS müşterisi olmadığı durum

Yetkiniz

bulunmamaktadır

Tek seferlik ödemelerde rıza isteğinde ÖHK kimlik bilgileri bulunmamaktadır.

Diğer akışlarda rıza isteğinde müşteri olma kontrolü yapılabilir.

Zorunlu

HHS’nin ÖHK için yaptığı kontrollerin başarısız olduğu durum

Yetkiniz

bulunmamaktadır

HHS'nin, ÖHK için iç sistemlerinde yaptığı kontrollerin başarısız olması. Örneğin:

Müşterinin henüz bankacılık hizmet sözleşmesi gibi Internet şubesi üzerinde işlem yapmasını engelleyen eksikleri olması durumunda veya kurumsal kullanıcıda vekalet süresinin dolması/eksik doküman olması durumunda kanal üzerinde işlem yapamadığı durum

Zorunlu

Başarısız GKD

Yetkiniz

bulunmamaktadır

1-ÖHK'nın GKD için gerekli 2FA bilgilerini sağlayamaması

2- HHS risk algısına göre 12 nolu hata kodunu dönmek yerine 14 nolu hata kodunu da YÖS’e dönebilir.

Zorunlu

ÖHK isteği ile GKD’den vazgeçildiği durum (Ör: HHS ekranında yer alan VAZGEÇ butonuna basmış olabilir. )

Müşteri işlemden vazgeçmiştir.

1- HHS ekranında yer alan VAZGEÇ butonuna basılması durumu (Hem ÖHK login olmadan önce hem de GKD sonrası (xxxx xxxxx öncesi) VAZGEÇ butonu olabilir.)

2-Müşteri Banka login ekranında herhangi bir aksiyon almadan beklemiştir ve HHS GKD zaman aşımı süresi 5 dakikadan kısadır.

Zorunlu

Diğer

İşleminiz gerçekleştirileme miştir.

Opsiyonel

GKD sırasında iletilen rıza no eğer HHS’nin sisteminde bulunamazsa durumu güncellenecek bir rıza no da olmayacaktır. HHS kendi önyüzünde bu duruma uygun bir mesaj gösterebilir. YÖS’e de Diğer hata kodu ile bu durumu iletebilir.

6. Ödeme Emri Başlatma Hizmeti

Ödeme emri başlatma işlemi havale, FAST ya da PÖS ödemesiyle sonuçlanabilir. Ödeme işleminin amacı kişiden kişiye para transferi, e-ticaret ödemesi gibi farklı ödeme türleri olabilir. Ödemenin amacına göre ÖBHS’nin ileteceği veri setinde farklılaşmalar olabilir.

Ödeme Emri Başlatma Hizmeti 5 temel akışdan oluşur:

0. Ödeme Emri Başlatma İsteğinin tetiklenmesi: ÖHK ÖBHS mobil uygulama ya da websitesinden ödeme emrini başlatır.

1. Ödeme Xxxx Xxxx Xxxxxlanması: ÖBHS, “Ödeme Emri Başlatma” işlemi için izin oluşturulması isteğini HHS’ye iletir.

2. Ödeme Emri Rızasının Yetkilendirilmesi: HHS, gerekli gördüğü durumlarda ÖHK’yı GKD ile

doğrular ve ödeme emri rızasına erişim için erişim belirteci tanımlanmasını temin eder.

3. Ödeme Emrinin Başlatılması: ÖBHS, “ödeme emri”ni HHS’ye iletir.

4. Ödeme Xxxx Xxxx Xxxxxx, Ödeme Emri Durumu, Ödeme Emri Detayı Sorguları: ÖBHS, Ödeme Xxxx Xxxx Xxxxxx, Ödeme Emri Durumu, Ödeme Emri Detayı bilgilerini isteğe bağlı olarak sorgulayabilir.

Şekil 4: Ödeme Emri Başlatma Hizmeti Üst Düzey İş Akışı

Ödeme Emri Başlatma Hizmeti için Erişim Adresleri (Endpoints)

Tablo 6: Ödeme Emri Başlatma Hizmeti İçin Erişim Adresleri

Etki Alanı (Scope) =“odeme_emri”

Kaynak

HTTP

işlemi

Erişim Adresi

Zorunlu

/ İsteğe Bağlı

Yetkilendir

me Türü

İmzalama

İstem

Nesnesi

Yanıt

Nesnesi

odeme- emri- rizasi

POST

POST /odeme- emri-rizasi

İstemci

Kimlik Bilgileri

İmzalı İstek ve Yanıt

OdemeEmri RizasiIstegi

OdemeEmriRi zasi

erisim- belirteci (GKD

için)

POST

POST/erisim- belirteci

İstemci Kimlik Bilgileri

İmzalı İstek ve Yanıt

ErisimBelirte ciIstegi

ErisimBelirteci

2.1

odeme- emri- rizasi

GET

GET /odeme- emri- rizasi/{rizaNo}

İstemci Kimlik Bilgileri

İmzalı Yanıt

OdemeEmriRi zaYaniti

odeme- emri

POST

POST /odeme- emri

İstemci Kimlik Xxxxxxxxx & Yetkilendirm

e Xxxx (GKD)

İmzalı İstek ve Yanıt

OdemeEmriI stegi

OdemeEmri

3.1

odeme- emri

GET

GET /odeme- emri/{odeme EmriNo}

İstemci Kimlik Xxxxxxxxx & Xxxxxlendirm

e Xxxx (GKD)

İmzalı Yanıt

OdemeEmri

6.1. ADIM 0 - Ödeme Emri Başlatma Isteği

o ÖHK, ÖBHS uygulamasında (web arayüzü/mobil uygulama) ödeme emri başlatma işlemine

onay verir.

o Gönderen hesap detaylarının bu aşamada belirtilmesi zorunlu değildir.

6.2. ADIM 1 - Ödeme Emri Rızasının Hazırlanması

Şekil 5: Ödeme Emri Rızasının Hazırlanması

o ÖBHS, ödeme hizmeti kullanıcı hesabının bulunduğu HHS’ye bağlanarak ödeme emri rıza kaynağının oluşturulmasını (odemeEmriRizasi) sağlar.

o POST isteği TLS protokolü tesis edilen iletişim katmanı üzerinden gerçekleştirilir. TLS için nitelikli sertifikalar kullanılır.

o POST isteğinin başlığındaki alanlar ve istemcinin sertifikasındaki özel alanlar kullanılarak istemcinin yetkilendirilmesi sağlanır:

▪ İstekte bulunan ÖBHS yetkilendirilmiş mi?

▪ İstekte bulunan yetkilendirilmiş ödeme hizmeti sağlayıcısı XXXX rolüne sahip mi?

▪ İstekte bulunulan HHS kodu doğru mu?

o POST başarılı olursa, HHS, ödeme emri için içeride rıza olup olmamasına bakılmaksızın yeni bir rıza tanımlayıcısı RizaNo içeren odemeEmriRizasi yanıt olarak döner.

o 1 ÖHK'nın 1 YÖS için 1HHS'de istediği kadar rızası olabilir.

o HHS tarafında RizaDurumu değişkeninin durumu “Yetki Bekleniyor” olarak güncellenir.

o YÖS’ün doğrulama ekranı olarak ÖHK’ya açacağı URL adresini de ilgili rıza numarasına göre oluşturur. Burada 2 farklı yöntemle URL oluşturabilir.

• Statik URL : HHS’nin base pathi/alt-dizin/{rızaNo}Örnek hhsYonAdr :

xxxxx://xxxxx.xxx.xx/xxxxx/xx00000x00x000x00xx0x000xxx0000x

Bu adres için ilgili doğrulama sayfası önden hazırlanmalı ve ÖHK’nın doğrulama sayfasına erişimi için yayınlanmış olmalıdır (publish edilmelidir).

• Dinamik URL:

HHS’nin base pathi/alt-dizin/GKD Karşılama Ekranı?rizano={rızano} Örnek:

xxxxx://xxxxx.xxx.xx/xxxxx/xxx?xxxxxxxxx00000x00x000x00xx0x000xxx0000x

POST /odeme-emri-rizasi

İSTEK:

ÖBHS, bu API erişim adresinden HHS’ye yeni bir OdemeEmriRizasi oluşturulması için istekte bulunur:

• ÖBHS, ödeme emri başlatma isteği olduğunu HHS’ye bildirir.

• ÖBHS, ÖHK’nın, ÖBHS arayüzünden verdiği rızanın (“Ön Onay”) bir kopyasının HHS nezdinde müşteri tarafından onaylanması için HHS’ye gönderilmesini sağlar.

• HHS; istek mesajında yer alan alanların API dökümanında belirtilen şartları sağlayacak şekilde zorunluluk, uzunluk ve içerik kontrollerini yapar. (Zorunlu)

• HHS; YÖS API ile alınan ÖBHS bilgilerinin içerisinde yer alan yönlendirme ve bildirim adresleri ile ödeme emri rızası nesnesi request mesajında paylaşılan adreslerin uyumlu olup olmadığının kontrollerini yapar. (Zorunlu)

• HHS; kimlik bilgileri nesnesinde eğer kimlik bilgileri iletilmiş ise; bu veri ile ÖHK’nın HHS müşterisi olup olmadığının kontrollerini yapar. Bu kontrol hem bireysel hem de kurumsal ÖHK’lar için yapılmalıdır. (Koşullu Zorunlu)

• HHS kimlik bilgisi ile gönderen unvanının uyumlu olduğunun kontrol eder. (Zorunlu)

• Gönderen Hesap Numarası ile ilgili Tablo7’de belirtilen kontroller yapılmalıdır. (Zorunlu)

• HHS, ödeme için benzersiz “RizaNo” ile “OdemeEmriRizasi” nesnesi oluşturur ve ÖBHS’ye döner.

• HHS, OdemeEmriRizasi oluşturduğu anda durumunu “Yetki Bekleniyor” olarak düzenler. Bu aşamada ÖHK’nın HHS tarafından tanımlanmış ve isteğin veri alanında gönderen hesaba (borçlandırılacak hesaba) ilişkin bir bilgisinin olması gerekmez.

Hesap bakiye kontrolünün rıza aşamasında yapılmaması gerekmektedir. Çünkü ÖHK ödeme emri gerçekleşene kadar hesabına para eklemesi yapabilir.

POST /odeme-emri-rizasi isteğinin (REQUEST) gövdesinde (BODY) “odemeEmriRizasiIstegi” nesnesi (Tablo-7) kullanılır. İstek başarıyla sonuçlanırsa HHS kaynak sunucusunda “odemeEmriRizasi” (Tablo-8) nesnesi oluşturulur.

BAŞARILI İSTEK:

Tablo 7: “OdemeEmriRizasiIstegi” nesnesi

Alan Adı

JSON

Alan Adı

Format: Veri

modeli İsmi

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

HHS tarafından ödeme emri rızası oluşturulması sırasında yapılması gereken kontrol ve işlemler

Katılımcı Bilgisi

katilimci Blg

Kompleks:Katilimci Bilgisi

Katılımcılara atanmış kod bilgileridir.

>Hesap Hizmeti

Sağlayıcısı Kodu

hhsKod

AN4

İsteğin iletildiği Hesap Hizmeti Sağlayıcısının kodudur. (Nezdinde ÖH

bulunduran kuruluş kodu. Örneğin, Banka, Elektronik Para Kuruluşu ve Ödeme Kuruluşu)

HHS, hhsKod’un kendisine ait olduğunu ve istek başlığındaki x-aspsp-code değeri ile aynı olduğunu kontrol eder.

Hata durumunda TR.OBHS.Connection.InvalidASPSP hata kodunu döner.

> Yetkili Ödeme Hizmeti Sağlayıcısı Kodu

yosKod

AN4

İsteği gönderen Yetkili Ödeme Hizmeti Sağlayıcısı (YÖS) kodudur

HHS, yosKod’un geçerli bir Ödeme Hizmeti Sağlayıcısı Kodu olduğunu ve istek başlığındaki x-tpp-code değeri ile aynı olduğunu kontrol eder. Hata durumunda TR.OBHS.Connection.InvalidTPP hata kodunu döner.

GKD

gkd

Kompleks:Gkd

Alan Adı

JSON

Alan Adı

Format: Veri

modeli İsmi

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

HHS tarafından ödeme emri rızası oluşturulması sırasında yapılması gereken kontrol ve işlemler

> Yetkilendirme

Yöntemi

yetYntm

AN1

TR.OHVPS.DataCode.GkdTur sıralı veri türü değerlerlerinden birini alır.

Yetkilendirme yöntemi, XXXX tarafından belirtilmeyebilir.

HHS, ÖBHS’nin belirlediği yöntemi dikkate alarak kendi belirlediği yöntemi kullanır.

> Yönlenme

Adresi

yonAdr

AN1..1024

Yönlendirmeli güçlü kimlik doğrulama için zorunlu. YÖS’ün ileteceği adrestir.

YÖS Yönlendirmeli GKD yöntemi ile akışı destekliyorsa, yetYntm

değişkeninden bağımsız olarak yönlendirme adresini iletmelidir.

Durum kodu(drmKod), yönlendirme adresine parametre olarak

eklenmelidir.

HHS, müşteri uygulama / tarayıcısını bu

alanda belirtilen adrese yönlendirir.

> Bildirim Adresi

bldAdr

AN1..1024

Ayrık güçlü kimlik doğrulama için zorunlu. YÖS’ün ileteceği

adrestir.

YÖS Ayrık GKD yöntemi ile akışı destekliyorsa, yetYntm

değişkeninden bağımsız olarak bildirim adresini iletmelidir.

Durum kodu(drmKod), yönlendirme adresine parametre olarak

eklenmelidir.

HHS, ayrık GKD sonrası bu alanda belirtilen adrese otorizasyon kodunu (authentication code) iletir.

Ödeme Başlatma

odmBslt m

Kompleks: OdemeBaslatma

> Kimlik

kmlk

Kompleks:Kimlik

Alan Adı

JSON

Alan Adı

Format: Veri

modeli İsmi

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

HHS tarafından ödeme emri rızası oluşturulması sırasında yapılması gereken kontrol ve işlemler

>> Kimlik Türü

kmlkTur

AN1

TR.OHVPS.DataCode.KimlikTur sıralı veri türü değerlerlerinden birini alır.

Çerçeve sözleşme kapsamındaki ödemelerde kullanımı zorunludur.

HHS geçerli bir Kimlik Numarası Türü olduğunu kontrol eder.

Kurum adına yapılan (ticari) ödemelerde, kurum adına işlem yapan kullanıcının kimlik türünün bu alanda gönderilmesi zorunludur.

>> Kimlik Verisi

kmlkVrs

AN1..30

HHS nezdinde kullanıcı doğrulamasında kullanılan tanımlayıcıdır.

TR.OHVPS.DataCode.KimlikTur değerine göre uzunluk ve formatı değişir.

Çerçeve sözleşme kapsamındaki ödemelerde kullanımı zorunludur.

HHS, XXXX tarafından iletilmesi durumunda Kimlik Verisi üzeriden çapraz kontroller uygulamalı ve Kimlik Verisini temel alarak GKD gerçekleştirmelidir.

Pasaport numarasına ilişkin kontroller HHS'nin halihazırda kullandığı veri, akış ve tabi olduğu diğer düzenlemelerdeki işleyiş ile aynı şekilde ele alınmalıdır.

Kurum adına yapılan (ticari) ödemelerde, kurum adına işlem yapan

Alan Adı

JSON

Alan Adı

Format: Veri

modeli İsmi

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

HHS tarafından ödeme emri rızası oluşturulması sırasında yapılması gereken kontrol ve işlemler

kullanıcının kimlik türünün bu alanda

gönderilmesi zorunludur.

>> Kurum Kimlik

Türü

krmKmlk Tur

AN1

Kurum adına yapılan ödemelerde ÖHK’nın altında tanımlı olduğu tüzel kişilik için kullanılan kurum kimlik türüdür.

TR.OHVPS.DataCode.KurumKimlikTur sıralı veri türü değerlerlerinden birini alır.

Kurum adına yapılan (ticari) ödemelerde kullanımı zorunludur.

HHS geçerli bir Kurum Kimlik Numarası Türü olduğunu kontrol eder.

>> Kurum Kimlik Verisi

krmKmlk Vrs

AN1..30

Kurum adına yapılan ödemelerde ÖHK’nın altında tanımlı olduğu tüzel kişilik için kullanılan kurum kimlik verisidir. TR.OHVPS.DataCode.KurumKimlikTur değerine göre uzunluk ve formatı değişir.

Kurum adına yapılan (ticari) ödemelerde kullanımı zorunludur.

HHS, ÖBHS tarafından iletilmesi durumunda Kurum Kimlik Verisi üzeriden çapraz kontroller uygulamalıdır.

>> Ödeme Hizmeti Kullanıcısı Türü

ohkTur

AN1

TR.OHVPS.DataCode.OhkTur sıralı veri türü değerlerlerinden birini alır (B: Bireysel, K:Kurumsal)

Kurum adına yapılan ödemelerde K değerini alır. Kurum Kimlik Türü ve Kurum Kimlik Verisi alanlarının girilmiş olduğu çapraz olarak kontrol edilir.

> İşlem Tutarı

islTtr

Kompleks:Tutar

>> Para Birimi

prBrm

AN3

Para Birimi.

Karekod akışında, FAST Karekod Veri Organizasyonundaki 53:

(Para Birimi) alanında tanımlı Tutar verisi kullanılır.

HHS geçerli bir para birimi olduğu

kontrol eder.

Alan Adı

JSON

Alan Adı

Format: Veri

modeli İsmi

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

HHS tarafından ödeme emri rızası oluşturulması sırasında yapılması gereken kontrol ve işlemler

>> Tutar

ttr

N1..18

ÖBHS'nin ön yüzde kullanıcıdan teyit aldığı tutar.

Karekod akışında, FAST Karekod Veri Organizasyonundaki 54: (Tutar) alanında tanımlı Tutar verisi kullanılır.

Örneğin 1,20 TRY için tutar alanında “120” değeri iletilir

> Gönderen

gon

Kompleks:Hesap

>> Unvan

unv

AN3..140

Gönderenin unvanıdır.

HHS, bu bilgiyi ÖBHS sisteminden gelen veri yerine FAST’a

iletirken kendi sisteminden alabilir.

HHS’nin bu veri ile kendi sistemlerindeki verinin farklı olması ve Kimlik Numarası ile eşleşmemesi durumunda ödeme emri başlatma isteği reddedilir.

ÖBHS verisi ile HHS verisinin farklılaşması durumunun ise risk değerlendirme sistemlerine girdi olarak kullanması tavsiye edilir.

>> Hesap

Numarası

hspNo

AN26

XXXX'xxx ön yüzünden daha önce kayıt altına alınmış hesaplar arasından seçtirdiği veya müşteriye girdiği IBAN’dır.

XXXX tarafından iletilmediği durumda, gönderen hesap bilgisini müşteri tarafından HHS’nin dijital kanalında GKD sonrasında seçilebilir. Bu amaçla ÖBHS arayüzünde HHS seçtirilmelidir.

XXXX tarafından iletildiği durumda

IBAN içerisindeki HHS kodunun istek başlığındaki HHS kodu ile aynı olduğu (hesabın HHS’ye aitliğinin kontrolü) IBAN’ın doğruluğu (kontrol basamağı doğrulaması)

Hesap numarasının ÖHK’ya ait olduğu

Alan Adı	JSON Alan Adı	Format: Veri modeli İsmi	Zorunlu / Koşullu / İsteğe bağlı	Açıklama	HHS tarafından ödeme emri rızası oluşturulması sırasında yapılması gereken kontrol ve işlemler
				Hesap Referansı kullanılıyorsa Hesap Numarası kullanılmayabilir. Hesap referansı ile ödeme emri rızası başlatılacak ise HHS hesap referansı değeri ile ilişkilendirilmiş mevcut bir hesap bilgisi rızası var mı kontrol etmelidir. Eğer aktif bir rızası yok ise TR.OBHS.Business.InvalidContent hatası verilmelidir.	HHS’ye özel ödeme izni verilmeyen farklı statülerin bulunması durumu kontrol edilir. Kontrol başarısız olduğunda XX.XXXX.Xxxxxxxx. InvalidAccount hatası YÖS’e iletilir.
>> Hesap Referansı	hspRef	AN5..40	İ	HHS tarafından hesap için atanan biricik tanımlıyıcıdır (uuid). YÖS bazında farklılaşması gerekmez. ÖBHS’nin aynı zamanda HBHS olduğu durumda müşteri rızası tesis edilmiş bir hesabın referansı üzerinden de ödeme başaltılabilir. Hesap Numarası kullanılıyorsa Hesap Referansı kullanılmayabilir.	HspRef'e bağlı IBAN değiştiğinde yeni IBAN'ın da ilgili HspRef ile ilişkilendirilmesi beklenmektedir. Bu durumda, HBHS, HspRef ile sorguya geldiğinde HHS'nin yeni IBAN ve hesap hareketlerini dönebilmesi mümkün olacaktır. HspRef’in, IBAN değiştiğinde değiştirilmemesi tavsiye edilmektedir.
> Alıcı	alc	Kompleks:Hesap	Z
>> Unvan	unv	AN3..140	K	Kolay Adres Sistemi kullanılmıyorsa zorunludur. Alıcının unvanıdır. ÖBHS ekranlarından girişi yapılabileceği gibi ÖBHS’nin kayıtlı alıcılarından yapılan seçimle de doldurup gönderebildiği bilgi olabilir. FAST-TR Karekod Veri Organizasyonunda; İşyeri tarafından sunulan uzun karekod yapısının 59: alanında tanımlı İşyeri adı alanıdır

Alan Adı

JSON

Alan Adı

Format: Veri

modeli İsmi

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

HHS tarafından ödeme emri rızası oluşturulması sırasında yapılması gereken kontrol ve işlemler

Kişiden Kişiye Ödeme Karekod Yapısının 07: alanında tanımlı

Ödeme Alıcısının Adı ve Soyadı alanıdır.

>> Hesap

Numarası

hspNo

AN26

Alıcının Hesap Numarası (IBAN) alanıdır.

Kolay Adres Sistemi kullanılmıyorsa zorunludur.

Karekod akışında, FAST Karekod Veri Organizasyonundaki 30- 01: alanında tanımlı İş Yeri IBAN verisi kullanılır.

Alıcının birden fazla hesabının kullanılabilir olduğu durumlarda (özellikle işyeri ödemelerinde HHS nezdindeki hesap (on-us havale akışı) tercih edilmelidir.

HHS (Gönderen Katılımcı) tarafından IBAN doğrulaması (kontrol basamağı doğrulaması) yapılır.

>> Kolay Adres

kolas

Kompleks:Kolas

>>> Kolas Türü

kolasTur

AN1

TR.OHVPS.DataCode.KolasTur sıralı veri türü değerlerinden birini alır.

Alıcı Hesap Numarası girilmediyse kullanımı zorunludur ve

Kolay Adres Tipi alanıyla birlikte kullanılır.

HHS (Gönderen FAST katılımcısı) tarafından KOLAS Servisine yapılan sorguda girdi olarak kullanılır.

>>> Kolas Değeri

kolasDgr

AN7..50

Müşterinin eklediği, HHS (FAST katılımcısı) tarafından doğrulanmış Kolay Adres değeridir. Alabileceği değerler BKM “Kolay Adresleme

Sistemi Uygulama Kuralları” belgesinde tanımlıdır.

Hesap Numarası girilmediyse kullanımı zorunludur ve Kolay Adres Tipi alanıyla birlikte kullanılır.

HHS (Gönderen FAST katılımcısı) tarafından KOLAS Servisine yapılan sorguda girdi olarak kullanılır.

Alan Adı

JSON

Alan Adı

Format: Veri

modeli İsmi

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

HHS tarafından ödeme emri rızası oluşturulması sırasında yapılması gereken kontrol ve işlemler

> Karekod

kkod

Komplek:Karekod

>> Akış Türü

aksTur

AN2

TR.OHVPS.DataCode.KareKodAksTur sıralı veri

değerlerinden birini alır.

Kolay Adresi Sistemi ile birlikte kullanılmaz.

>> Referansı

kkodRef

AN1..12

Karekod referans numarasını gösterir.

Okunan karekodda referans değeri varsa kullanılması

zorunludur.

Karekod ilke ve kurallar belgesinde tanımlandığı şekilde kullanılması gerekmektedir.

Kolay Adresi Sistemi ile birlikte kullanılmaz.

>> Üretici Kodu

kkodUrtc Kod

AN4

Karekod üreticisinin kodu.

Ödeme Hizmeti Sağlayıcıları ve TCMB tarafından uygun görülen ödeme sistemi işleticisi TR Karekod üretebilmek için BKM’ye kayıt başvurusu yaparak karekod üretici kodu alabileceklerdir. Bankalar EFT kodlarını kullanacak olup ayrıca kayıt yaptırmalarına gerek bulunmamaktadır. 4 haneden kısa değerlerin sol tarafı ’0’ karakteri ile tamamlanmalıdır.

Alan Adı

JSON

Alan Adı

Format: Veri

modeli İsmi

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

HHS tarafından ödeme emri rızası oluşturulması sırasında yapılması gereken kontrol ve işlemler

> Ödeme Ayrıntıları

odmAyr

Komplek: OdemeAyrintilari

>> Ödeme Kaynağı

odmKyn k

AN1

Ödemenin başlattığı kaynağı belirtir. TR.OHVPS.DataCode.OdemeKaynak sıralı veri değerlerinden birini alır.

HHS geçerli bir Ödeme Kaynağı kodu kullanıldığını kontrol eder.

>> Ödeme Amacı

odmAmc

AN2

TR.OHVPS.DataCode.OdemeAmaci sıralı veri değerlerinden birini alır.

Karekod akışında, FAST Karekod Veri Organizasyonundaki 62-

08: alanında tanımlı Ödeme Amacı verisi kullanılır.

HHS geçerli bir Ödeme Amacı kodu olduğunu kontrol eder.

>> Referans Bilgisi

refBlg

AN1..140

Ödemeye özel Referans Bilgisi alanıdır. Karekod işlemi değil

ise zorunludur.

Kişiden kişiye fon aktarımlarda: Gün içerisinde ÖHK için biricik olarak oluşturan referans bilgisi

E-ticaret işlemlerinde sipariş/takip numarası/müşteri/abone numarası

Karekod akışında, FAST Karekod Veri Organizasyonundaki

62-01: alanında tanımlı Fatura Numarası 62-06: alanında tanımlı Müşteri Numarası verilerinden biri kullanılır.

HHS bu değeri GKD için kullandığı önyüzünde “işlem doğrulama kodunun” bir unsuru olarak göstermelidir.

Alan Adı

JSON

Alan Adı

Format: Veri

modeli İsmi

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

HHS tarafından ödeme emri rızası oluşturulması sırasında yapılması gereken kontrol ve işlemler

>> Açıklama

odmAckl m

AN1..50

ÖBHS’nin ÖHK’dan aldığı ya da kendisinin atadığı işlem açıklaması bilgisi.

> ÖBHS Masraf Tutarı

ObhsMsr fTtr

Kompleks:Tutar

>> Para Birimi

prBrm

AN3

Para birimi (TRY, USD, EUR vb.).

>> Tutar

ttr

N1..18

ÖBHS’nin işlemle ilgili ÖHK’nın borçlandırılmasını belirttiği masraf tutarı. İşlem Tutarı ile aynı para biriminde olmalıdır.

Örneğin 1,20 TRY için tutar alanında “120” değeri iletilir

İşyeri Ödeme

Bilgileri

isyOdmB lg

Kompleks:IsyeriOd emeBilgileri

İşyeri ödemelerinde kullanılabilecek alanlardır.

Karekodlu işyeri ödemesi akışında bu alanlar dolu geldiği için isteğe bağlı olarak gönderilebilir.

İşyeri Ödeme Bilgileri alanlarının en az birinin dolu olması durumunda istekte yer alır.

> İşyeri Kategori Kodu

isyKtgKo d

İşlemin, ISO 18245:2003 uyumlu İşyeri Kategori Kodudur

(Merchant Category Code, MCC).

Ödeme Amacı = ‘06’ ya da ‘04’ olan ödeme işlemleri için

doldurulabilir.

Alan Adı

JSON

Alan Adı

Format: Veri

modeli İsmi

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

HHS tarafından ödeme emri rızası oluşturulması sırasında yapılması gereken kontrol ve işlemler

> Alt İşyeri

Kategori Kodu

altIsyKtg Kod

İşlem alt işyerinden gerçekleştiriliyorsa, ISO 18245:2003 uyumlu İşyeri Kategori Kodudur (Merchant Category Code, MCC).

>Üye İş Yeri Tekil

Kimlik

genelUy eIsyeriN o

AN8

İşyeri kayıt sisteminde kayıtlı İşyeri için BKM tarafından üretilmiş olan genel işyeri numarasıdır (GlobalMerchantId) 8 haneden küçük gönderiminde başa ‘0’ eklenmelidir.

Örnek değer ‘01630618’

BAŞARILI YANIT:

POST işleminin RESPONSE gövdesini (BODY) oluşturan “OdemeEmriRizasi” nesnesi Tablo-8’deki parametrelerden oluşur:

Tablo 8: “OdemeEmriRizasi” nesnesi

Alan Adı

JSON Alan

Adı

Format

Zorunlu /

Koşullu /

Açıklama

Riza Bilgileri

rzBlg

Kompleks: RizaBilgileri

> Rıza No

rizaNo

AN1..128

OdemeEmriRızasi nesnesinin oluşturulması esnasında HHS kaynak sunucusu tarafından atanan biricik tanımlayıcı

> Oluşturma Zamanı

olusZmn

ISODateTime

OdemeEmriRizasi nesnesinin oluşturulma zamanı

> Güncellenme Zamanı

gnclZmn

ISODateTime

OdemeEmriRizasi nesnesinin güncellenme zamanı

> Xxxx Xxxxxx

rizaDrm

AN1

TR.OHVPS.DataCode.RizaDurumu sıralı veri tipini değerlerinden birini alır.

> Rıza Iptal Detay Kodu

rizaIptDtyKod

AN2

Rıza durumunun iptal olduğu durumda zorunludur. Alabileceği değerler 4. Bölümde detaylandırılmıştır.

Katılımcı Bilgisi

katilimciBlg

Kompleks:Katilimci Bilgisi

Katılımcılara atanmış kod bilgileridir.

>Hesap Hizmeti Sağlayıcısı

Kodu

hhsKod

AN4

İsteğin iletildiği Hesap Hizmeti Sağlayıcısının kodudur. (Nezdinde ÖH bulunduran kuruluş kodu. Örneğin, Banka, Elektronik Para Kuruluşu ve Ödeme Kuruluşu)

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu /	Açıklama
> Yetkili Ödeme Hizmeti Sağlayıcısı Kodu	yosKod	AN4	Z	İsteği gönderen Yetkili Ödeme Hizmeti Sağlayıcısı (YÖS) kodudur
GKD	gkd	Kompleks:Gkd	Z
> Yetkilendirme Yöntemi	yetYntm	AN1	Z	TR.OHVPS.DataCode.GkdTur sıralı veri türü değerlerlerinden birini alır.
> Yönlenme Adresi	yonAdr	AN1..1024	K	Yönlendirmeli güçlü kimlik doğrulama için zorunlu.
> Bildirim Adresi	bldAdr	AN1..1024	K	Ayrık güçlü kimlik doğrulama için zorunlu.
> HHS Yönlenme Adresi	hhsYonAdr	AN1..1024	K	GKD doğrulama bilgilerinin girilebilmesi için uygulamadan açılacak yönlendirme sayfasının adresi
> Yetkilendirme Tamamlanma Zamanı	yetTmmZmn	ISODateTime	Z	Yetkilendirme akışının tamamlanması gereken son zamanı gösterir. HHS tarafından maksimum 5 dk içinde işlem tamamlanacak şekil zaman damgası oluşturulur. Zaman aşımı olduğunda HHS’nin GKD’ye izin vermeyecek şekilde hata mesajı vermesi gerekmektedir. Rıza durumu Yetkilendirildi statüsüne geçene kadarki süredir.
Ödeme Başlatma	odmBsltm	Kompleks:OdemeB aslatma	Z
> Kimlik	kmlk	Kompleks:Kimlik	Z

Alan Adı

JSON Alan

Adı

Format

Zorunlu /

Koşullu /

Açıklama

>> Kimlik Türü

kmlkTur

AN1

TR.OHVPS.DataCode.KimlikTur sıralı veri türü değerlerlerinden birini alır.

>> Kimlik Verisi

kmlkVrs

AN1..30

HHS nezdinde kullanıcı doğrulamasında kullanılan tanımlayıcıdır.

TR.OHVPS.DataCode.KimlikTur değerine göre uzunluk ve formatı değişir.

>> Kurum Kimlik Türü

krmKmlkTur

AN1

Kurum adına yapılan ödemelerde ÖHK’nın altında tanımlı olduğu tüzel kişilik için kullanılan kurum kimlik türüdür.

TR.OHVPS.DataCode.KurumKimlikTur sıralı veri türü değerlerlerinden birini alır.

>> Kurum Kimlik Verisi

krmKmlkVrs

AN1..30

Kurum adına yapılan ödemelerde ÖHK’nın altında tanımlı olduğu tüzel kişilik için kullanılan kurum kimlik verisidir.

TR.OHVPS.DataCode.KurumKimlikTur değerine göre uzunluk ve formatı değişir.

>> Ödeme Hizmeti Kullanıcısı Türü

ohkTur

AN1

TR.OHVPS.DataCode.OhkTur sıralı veri türü değerlerlerinden birini alır (B: Bireysel, K:Kurumsal)

> İşlem Tutarı

islTtr

Kompleks:Tutar

>> Para Birimi

prBrm

AN3

Para Birimi.

Karekod akışında, FAST Karekod Veri Organizasyonundaki 53: (Para Birimi) alanında tanımlı Tutar verisi kullanılır.

>> Tutar

ttr

N1..18

ÖBHS'nin ön yüzde kullanıcıdan teyit aldığı tutar.

Karekod akışında, FAST Karekod Veri Organizasyonundaki 54: (Tutar) alanında tanımlı Tutar verisi kullanılır.

Alan Adı

JSON Alan

Adı

Format

Zorunlu /

Koşullu /

Açıklama

Örneğin 1,20 TRY için tutar alanında “120” değeri iletilir

> Gönderen

gon

Kompleks:Hesap

>> Unvan

unv

AN3..140

Gönderenin unvanıdır.

HHS, bu bilgiyi ÖBHS sisteminden gelen veri yerine FAST’a iletirken kendi sisteminden

alabilir.

>> Hesap Numarası

hspNo

AN26

ÖBHS'nin ön yüzünden daha önce kayıt altına alınmış hesaplar arasından seçtirdiği veya müşteriye girdiği IBAN’dır.

ÖBHS tarafından iletilmediği durumda, gönderen hesap bilgisini müşteri tarafından HHS’nin dijital kanalında GKD sonrasında seçilebilir. Bu amaçla ÖBHS arayüzünde HHS seçtirilmelidir.

GKD sonrası HHS ekranında seçilen Hesap Numarası POST işleminin yanıtında dönülemez ancak isteğe bağlı GET sorgusu ile dönülebilir.

Hesap Referansı kullanılıyorsa Hesap Numarası kullanılmayabilir.

>> Hesap Referansı

hspRef

AN5..40

HHS tarafından hesap için atanan biricik tanımlıyıcıdır (uuid). YÖS bazında farklılaşması

gerekmez.

ÖBHS’nin aynı zamanda HBHS olduğu durumda müşteri rızası tesis edilmiş bir hesabın referansı üzerinden de ödeme başlatılabilir.

GKD sonrası HHS ekranında seçilen Hesap Referansı POST işleminin yanıtında dönülemez ancak isteğe bağlı GET sorgusu ile dönülebilir.

Alan Adı

JSON Alan

Adı

Format

Zorunlu /

Koşullu /

Açıklama

Hesap Numarası kullanılıyorsa Hesap Referansı kullanılmayabilir.

> Alıcı

alc

Kompleks:Hesap

>> Unvan

unv

AN3..140

Kolay Adres Alıcı Sorgusunda başarılı sorgu sonucunda dönülen adres kaydı yaptırmış olan alıcının maskeli ad-soyadı veya maskeli ticari unvan bilgisidir. Kolas’tan dönen “account owner” alanı kullanılmalıdır.

Kolay adres değil ise ÖBHS tarafından istek mesajında iletilen unvan bilgisidir.

>> Hesap Numarası

hspNo

AN26

ÖBHS tarafından istek mesajında iletilip doğrulanan veya Kolay Adres Alıcı Sorgusunda başarılı sorgu sonucunda dönülen alıcı maskeli IBAN bilgisidir.

>> Kolay Adres

kolas

Kompleks:Kolas

>>> Kolas Türü

kolasTur

AN1

TR.OHVPS.DataCode.KolasTur sıralı veri türü değerlerinden birini alır.

Alıcı Hesap Numarası girilmediyse kullanımı zorunludur ve Kolay Adres Tipi alanıyla birlikte kullanılır.

>>> Kolas Değeri

kolasDgr

AN7..50

Müşterinin eklediği, HHS (FAST katılımcısı) tarafından doğrulanmış Kolay Adres değeridir. Alabileceği değerler BKM “Kolay Adresleme

Sistemi Uygulama Kuralları” belgesinde tanımlıdır.

Hesap Numarası girilmediyse kullanımı zorunludur ve Kolay Adres Tipi alanıyla birlikte kullanılır.

Alan Adı

JSON Alan

Adı

Format

Zorunlu /

Koşullu /

Açıklama

>>> KOLAS Referans

Numarası

kolasRefNo

N12

Kolay Adres Alıcı Sorgusunda başarılı sorgu sonucunda dönülen, BKM Kolay Adresleme Sistemi Uygulama Kuralları’nda tanımlı KOLAS tarafından ilgili sorguya özel olarak üretilmiş referans numarasıdır.

>>> KOLAS Hesap Türü

kolasHspTur

AN1

Kolay Adres Alıcı Sorgusunda başarılı sorgu sonucunda dönülen, BKM Kolay Adresleme Sistemi Uygulama Kuralları’nda tanımlı hesap türü bilgisidir:

TR.OHVPS.DataCode.KolasHspTur sıralı veri değerlerinden birini alır.

> Karekod

kkod

Kompleks:Karekod

>> Akış Türü

aksTur

AN2

TR.OHVPS.DataCode.KareKodAksTur sırali veri değerlerinden birini alır.

Kolay Adresi Sistemi ile birlikte kullanılmaz.

>> Referansı

kkodRef

AN1..12

Karekod referans numarasını gösterir.

>> Üretici Kodu

kkodUrtcKod

AN4

Karekod üreticisinin kodu.

Alan Adı

JSON Alan

Adı

Format

Zorunlu /

Koşullu /

Açıklama

> Ödeme Ayrıntıları

odmAyr

Kompleks:OdemeA yrintilari

>> Ödeme Kaynağı

odmKynk

AN1

Ödemenin başlattığı kaynağı belirtir. TR.OHVPS.DataCode.OdemeKaynak sıralı veri değerlerinden birini alır.

>> Ödeme Amacı

odmAmc

AN2

TR.OHVPS.DataCode.OdemeAmaci sıralı veri değerlerinden birini alır.

Karekod akışında, FAST Karekod Veri Organizasyonundaki 62-08: alanında tanımlı Ödeme Amacı verisi kullanılır.

>> Referans Bilgisi

refBlg

AN1..140

Ödemeye özel Referans Bilgisi alanıdır. Karekod işlemi değil ise zorunludur.

- Kişiden kişiye fon aktarımlarda: Gün içerisinde ÖHK için biricik olarak oluşturan

referans bilgisi

- E-ticaret işlemlerinde sipariş/takip numarası/müşteri/abone numarası

- Karekod akışında, FAST Karekod Veri Organizasyonundaki

- 62-01: alanında tanımlı Fatura Numarası

- 62-06: alanında tanımlı Müşteri Numarası verilerinden biri kullanılır.

>> Açıklama

odmAcklm

AN1..50

ÖBHS’nin ÖHK’dan aldığı ya da kendisinin atadığı işlem açıklaması bilgisi.

>> ÖHK Mesaj Alanı

ohkMsj

AN1.200

HHS’nin ÖHK’ya göstermek üzere ilettiği mesaj.

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu /	Açıklama
>>Ödeme Sistemi	odmStm	AN1	Z	TR.OHVPS.DataCode.OdemeSistemi sıralı veri değerlerinden birini alır.
>> Beklenen Ödeme Zamanı	bekOdmZmn	ISODateTime	K	İşlemin yönlendirildiği ödeme sistemi PÖS ise ve PÖS işlem saatleri dışında ise işlemin yapılabileceği ilk zaman bilgisidir. Bu alan ileri vadeli ödemeler için düşünülmüştür. İlk fazda doldurulmasına gerek olmadığı düşünülmektedir.
> ÖBHS Masraf Tutarı	obhsMsrfTtr	Kompleks:Tutar	İ
>> Para Birimi	prBrm	AN3	Z	Para birimi (TRY, USD, EUR vb.).
>> Tutar	Ttr	N1..18	Z	ÖBHS’nin işlemle ilgili ÖHK’nın borçlandırılmasını belirttiği masraf tutarı. İşlem Tutarı ile aynı para biriminde olmalıdır. Örneğin 1,20 TRY için tutar alanında “120” değeri iletilir
> HHS Masraf Tutarı	hhsMsrfTtr	Kompleks:Tutar	İ
>> Para Birimi	prBrm	AN3	Z	Para birimi (TRY, USD, EUR vb.).
>> Tutar	Ttr	N1..18	Z	HHS’nin işlemle ilgili ÖHK’nın borçlandırılmasını belirttiği masraf tutarı. İşlem Tutarı ile aynı para biriminde olmalıdır. Örneğin 1,20 TRY için tutar alanında “120” değeri iletilir
İşyeri Ödeme Bilgileri	isyOdmBlg	Kompleks:IsyeriOd emeBilgileri	İ	İşyeri ödemelerinde kullanılabilecek alanlardır. Karekodlu işyeri ödemesi akışında bu alanlar dolu geldiği için isteğe bağlı olarak gönderilebilir.

Alan Adı

JSON Alan

Adı

Format

Zorunlu /

Koşullu /

Açıklama

isyOdmBlg alanlarının en az birinin dolu olması durumunda yanıtta yer alır.

> İşyeri Kategori Kodu

isyKtgKod

İşlemin, ISO 18245:2003 uyumlu İşyeri Kategori Kodudur (Merchant Category Code,

MCC).

Ödeme Amacı = ‘06’ ya da ‘04’ olan ödeme işlemleri için doldurulabilir

> Alt İşyeri Kategori Kodu

altIsyKtgKod

İşlem alt işyerinden gerçekleştiriliyorsa, ISO 18245:2003 uyumlu İşyeri Kategori Kodudur

(Merchant Category Code, MCC).

>Üye İş Yeri Tekil Kimlik

genelUyeIsyeriN o

AN8

İşyeri kayıt sisteminde kayıtlı İşyeri için BKM tarafından üretilmiş olan genel işyeri numarasıdır (GlobalMerchantId) 8 haneden küçük gönderiminde başa ‘0’ eklenmelidir. Örnek değer ‘81630618’

6.3. ADIM 2- Ödeme Emri Rızasının Yetkilendirilmesi

Şekil 6: Ödeme Emri Rızasının Yetkilendirilmesi

ÖBHS, ÖHK’nın ödeme emrini yetkilendirmesi isteğini iletir. Ödeme emrinin yetkilendirilmesi, HHS tarafından gerçekleştirilen Yönlendirme veya Ayrık GKD yöntemiyle yapılır.

o Yönlendirmeli doğrulama akışında, ÖBHS ÖHK’yı HHS’ye yönlendirir.

▪ ÖBHS tarafından yönlendirme, bir önceki adımdaki RizaNo’yu içerir.

▪ Yönlendirmenin RizaNo’yu içermesi sayesinde, HHS hangi ödeme emriyle ilişkili olarak yönlendirme yapıldığını ilişkilendirebilir.

▪ HHS, ÖHK için GKD sürecini işletir.

ÖHK’yı doğrularsa,

• ÖHK -bir önceki adımda seçmediyse- borçlu hesabını seçer.

• HHS, ödeme emri rıza kaynağının durumunu “Yetkilendirildi” olarak günceller.

• HHS, ÖHK’yı “olumlu yönlendirme akışı” ile ÖBHS tarafından tanımlanan yönlendirme adresine yönlendirir:

yonAdr?rizaDrm=Y&yetKod=xx&rizaNo=yy&rizaTip=O&drmKod=zzz

ÖHK’yı doğrulayamazsa,

• HHS, ödeme emri rıza kaynağının durumunu “Yetki İptal” olarak günceller.

• HHS, ÖHK’yı “olumsuz yönlendirme akışı” ile XXXX tarafından tanımlanan yönlendirme adresine yönlendirir:

yonAdr?rizaDrm=I&rizaNo=yy&rizaTip=O&drmKod=zzz

HHS tarafında oluşabilecek bir hata durumunun YÖS’e aktarılması gerektiği durumlar olabilir.

Bu durumda yonlendirme adresinde hata kodu parametresi zorunlu olarak iletilmelidir.

Hata açıklamalarının neler olabileceği ve YÖS’ün kendi uygulamasında bu hatayı ne şekilde göstereceği aşağıda tariflenmiştir.

yonAdr?rizaDrm=I&rizaNo=yy&rizaTip=O&rizaIptDtyKod=11&drmKod=zzz

URL’de iletilen “Rıza İptal Detay Kodu” Rıza durumları bölümünde (4. Bölüm) belirtilen hata kodları ile aynı olacak şekilde tasarlanmıştır. GKD sırasında yapılması gereken kontroller 5.3 bölümünde detaylandırılmıştır.

o Ayrık doğrulama akışında, HHS, ÖHK’nın ödeme emrini başlattığı uygulamadan farklı olabilecek bir “doğrulama” uygulamasında işlemi doğrulamasını ister.

▪ Ayrık akış ÖBHS’nin farklı bir kanal kullanarak yetkilendirme isteği göndermesiyle başlatılır.

▪ Bu yetkilendirme isteği, yetkilendirilecek ödeme emri rızasının eşleştirileceği ÖHK’nın bulunması için ilgili veriyi taşır.

▪ HHS, ÖHK’yı doğrular.

▪ ÖHK -bir önceki adımda seçmediyse- borçlandırılacak hesabını seçer.

▪ HHS, ödeme emri rıza kaynağının durumunu “Yetkilendirildi” olarak günceller.

Başarılı GKD sonrasında (rizaDrm=’Y’) ilgili rıza nesnesi için (belirli bir rizaNo) yetkilendirme kodunun (yetKod) alınmasının ardından erişim belirteci erişim adresine POST çağrısı yapılarak yetkilendirme kodu karşılığında erişim belirteci ve yenileme belirteci alınır. POST /erişim-belirteci erişim noktası EK-3’te açıklanmıştır.

Erişim belirteci alındıktan sonra; HHS, ödeme emri rıza kaynağının durumunu “Yetki Kullanıldı” olarak günceller.

6.4. ADIM 2.1 – Ödeme Emri Rızasının Sorgulanması (isteğe bağlı)

GKD işleminin başarıyla tamamlanıp Ödeme Emri Rızasının yetkilendirilmesi esnasında, gönderen hesap seçiminin HHS ekranında yapıldığı durumlar olabilir. Bu durumlarda ödeme emri isteğinde gönderen hesap bilgileri alanının zorunlu olması nedeniyle, OdemeEmriRizasi nesnesi sorgulanarak gönderen hesap bilgileri (hesap numarası ve/veya hesap referansı) alınmalıdır. HHS, “ADIM 2 -Ödeme Emri Rızasının Yetkilendirilmesi” akışında ÖHK’nın hesapları arasında seçim yapmasını ve seçilen hesap bilgisinin OdemeEmriRizasi nesnesine işler.

Şekil 7: “odemeEmriRizasi” nesnesinin sorgulanması (isteğe bağlı)

GET /odeme-emri-rizasi/{RizaNo}

ÖBHS, mevcut durumunu kontrol etmek için, oluşturulan bir OdemeEmriRizasi kaynağının durumunu isteğe bağlı olarak alabilir.

Durum

OdemeEmriRizasi kaynağı için kullanılabilecek durum göstergeleri şu şekildedir:

• Yetki Bekleniyor

• Yetkilendirildi

• Yetki Kullanıldı

• Yetki Ödeme Emrine Dönüştü

• Yetki Sonlandırıldı

• Yetki İptal

Ödeme emri rıza durum değişiklikleri 4.2 bölümünde detaylandırılmıştır.

BAŞARILI YANIT:

GET /odeme-emri-rizasi/{RizaNo} yanıtının (RESPONSE) gövdesinde (BODY) “OdemeEmriRizasiİstegi” nesnesi kullanılır. İstek başarıyla sonuçlanırsa HHS kaynak sunucusunda Tablo-8’de yer alan parametreleri içeren “OdemeEmriRizasi” oluşturulur.

Gönderen Hesap Bilgisinin, ADIM 2 (Ödeme Emri Rızasının Yetkilendirilmesi) sonrasında HHS ekranından seçildiği akışta “OdemeEmriRizasi” nesnesi güncellenir ve ÖBHS GET /odeme-emri-rizasi/{RizaNo} isteği yaparak güncel gönderen hesap bilgisi bilgisini de içeren “OdemeEmriRizasi” nesnesini çekmelidir.

6.5. ADIM 3- Ödeme Emrinin Oluşturulması

POST /odeme-emri ‌

Şekil 8: Ödeme Emrinin Oluşturulması

o ÖHK’nın Güçlü Kimlik Doğrulama ile işlemi yetkilendirmesi sonrasında, ÖBHS OdemeEmri kaynağını oluşturur.

o Ödeme emri (OdemeEmri) uygun ödeme kaynağına POST isteği yapılarak başlatılır.

• POST HHS tarafından işlenir: RizaDurumu “Yetki Kullanıldı” ise işleme başlanır.

• POST /odeme-emri-rizasi ile POST /odeme-emri isteklerinde istek alanların aynı olması beklenmektedir. HHS tarafından kontrolü xxxxxxxxxxxxx.XXXX verisindeki Gönderen Hesap Numarası ve Alıcı Hesap Numarasının aynı bankaya aitse HAVALE değilse FAST veya PÖS iş akışına geçilir.

• POST verisinin modele göre kontrolü yapılır (alan kontrolleri)

• POST verisinin mantıksal kontrolleri yapılır (IBAN kontrolü, çapraz alan kontroller)

• OdemeEmriDurumu “Gerçekleşti” / “Gönderildi” / “Gerçekleşmedi” olarak güncellenir.

o POST başarılı olursa, içerisinde OdemeEmriNo ve OdemeEmriDurumu değişkenleri de bulunan OdemeEmri nesnesi ÖBHS’ye döner ve RizaDurumu değişkenin değeri “Yetki Ödeme Emrine Dönüştü” olarak güncellenir.

BAŞARILI İSTEK:

Tablo 9: “OdemeEmriIstegi” nesnesi

Alan Adı

JSON Alan

Adı

Format

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler

FAST A01

PÖS M01

mesaj mapping

Riza Bilgileri

rzBlg

Kompleks: RizaBilgile ri

> Rıza No

rizaNo

AN1..128

OdemeEmriRızası nesnesinin oluşturulması esnasında HHS kaynak sunucusu tarafından atanan biricik tanımlayıcı.

> Oluşturma Zamanı

olusZmn

ISODateTi me

OdemeEmriRizasi nesnesinin oluşturulma zamanı

> Rıza Durumu

rizaDrm

AN1

TR.OHVPS.DataCode.RizaDurumu sıralı veri tipini değerlerinden birini alır.

Katılımcı Bilgisi

katilimciBlg

Kompleks: KatilimciBi lgisi

Katılımcılara atanmış kod bilgileridir.

>Hesap Hizmeti

Sağlayıcısı Kodu

hhsKod

AN4

İsteğin iletildiği Hesap Hizmeti Sağlayıcısının

kodudur. (Nezdinde ÖH bulunduran kuruluş kodu. Örneğin, Banka, Elektronik Para Kuruluşu ve Ödeme Kuruluşu)

HHS, hhsKod’un kendisine ait olduğunu ve istek başlığındaki x-aspsp-code değeri ile aynı olduğunu kontrol eder.

Gönderen katılımcı kodu (yani bankanın

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama	HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler	FAST A01 PÖS M01 mesaj mapping
					Hata durumunda TR.OBHS.Connection.InvalidASPSP hata kodunu döner.	FAST/PÖS’teki Katılımcı kodu)
> Yetkili Ödeme Hizmeti Sağlayıcısı Kodu	yosKod	AN4	Z	İsteği gönderen Yetkili Ödeme Hizmeti Sağlayıcısı (YÖS) kodudur	HHS, yosKod’un geçerli bir Ödeme Hizmeti Sağlayıcısı Kodu olduğunu ve istek başlığındaki x-tpp-code değeri ile aynı olduğunu kontrol eder. Hata durumunda TR.OBHS.Connection.InvalidTPP hata kodunu döner.	YosKod
GKD	Gkd	Kompleks: Gkd	Z
> Yetkilendirme Yöntemi	yetYntm	AN1	Z	TR.OHVPS.DataCode.GkdTur sıralı veri türü değerlerlerinden birini alır.
> Yönlenme Adresi	yonAdr	AN1..1024	K	Yönlendirmeli güçlü kimlik doğrulama için zorunlu.
> Bildirim Adresi	bldAdr	AN1..1024	K	Ayrık güçlü kimlik doğrulama için zorunlu.

Xxxx Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama	HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler	FAST A01 PÖS M01 mesaj mapping
> HHS Yönlenme Adresi	hhsYonAdr	AN1..1024	K	GKD doğrulama bilgilerinin girilebilmesi için uygulamadan açılacak yönlendirme sayfasının adresi
> Yetkilendirme Tamamlanma Zamanı	yetTmmZmn	ISODateTi me	Z	Yetkilendirme akışının tamamlanması gereken son zamanı gösterir. Rıza durumu Yetkilendirildi statüsüne geçene kadarki süredir.
Ödeme Başlatma	odmBsltm	Kompleks: OdemeBa slatma	Z
> Kimlik	kmlk	Kompleks: Kimlik	Z
>> Kimlik Türü	kmlkTur	AN1	Z	TR.OHVPS.DataCode.KimlikTur sıralı veri türü değerlerlerinden birini alır.	Çerçeve sözleşme kapsamındaki ödemelerde kullanımı zorunludur. Ödeme Emri Rizası Nesnesindeki Kimlik Numarası Türü verisi ile aynı olmalıdır. Kurum adına yapılan (ticari) ödemelerde, kurum adına işlem yapan kullanıcının kimlik

Alan Adı

JSON Alan

Adı

Format

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler

FAST A01

PÖS M01

mesaj mapping

türünün bu alanda gönderilmesi

zorunludur.

>> Kimlik Verisi

kmlkVrs

AN1..30

HHS nezdinde kullanıcı doğrulamasında kullanılan tanımlayıcıdır.

TR.OHVPS.DataCode.KimlikTur değerine göre uzunluk ve formatı değişir.

Çerçeve sözleşme kapsamındaki ödemelerde kullanımı zorunludur.

HHS, ÖBHS tarafından iletilmesi durumunda Kimlik Verisi üzeriden çapraz kontroller uygulamalı ve Kimlik Verisini temel alarak GKD gerçekleştirmelidir.

Ödeme Emri Rizası Nesnesindeki Kimlik Numarası verisi ile aynı olmalıdır.

Gerçek kişi tarafından yapılan ödemelerde,

1. HHS, Gönderen Adı ve Gönderen Hesap Numarasını ödeme emri isteğinde (Havale/FAST/PÖS) gönderir.

- Gönderen Adı ve diğer tüm müşteri bilgileri, Kimlik Numarası üzerinden elde edillir.

Pasaport numarasına ilişkin kontroller HHS'nin halihazırda kullandığı veri, akış ve

GonKimN / Psp

Alan Adı

JSON Alan

Adı

Format

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler

FAST A01

PÖS M01

mesaj mapping

tabi olduğu diğer düzenlemelerdeki işleyiş ile aynı şekilde ele alınmalıdır.

Kurum adına yapılan (ticari) ödemelerde, kurum adına işlem yapan kullanıcının kimlik verisi bu alanda gönderilebilmesi zorunludur.

>> Kurum Kimlik Türü

krmKmlkTur

AN1

Kurum adına yapılan ödemelerde ÖHK’nın altında tanımlı olduğu tüzel kişilik için kullanılan kurum kimlik türüdür.

TR.OHVPS.DataCode.KurumKimlikTur

sıralı veri türü değerlerlerinden birini alır.

Kurum adına yapılan (ticari) ödemelerde kullanımı zorunludur.

Ödeme Emri Rizası Nesnesindeki Kurum Kimlik Türü verisi ile aynı olmalıdır.

>> Kurum Kimlik Verisi

krmKmlkVrs

AN1..30

Kurum adına yapılan ödemelerde ÖHK’nın altında tanımlı olduğu tüzel kişilik için kullanılan kurum kimlik verisidir.

TR.OHVPS.DataCode.KurumKimlikTur

değerine göre uzunluk ve formatı değişir.

Kurum adına yapılan (ticari) ödemelerde kullanımı zorunludur.

Ödeme Emri Rizası Nesnesindeki Kurum Kimlik Verisi ile aynı olmalıdır.

GonKimN / VKN

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama	HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler	FAST A01 PÖS M01 mesaj mapping
>> Ödeme Hizmeti Kullanıcısı Türü	ohkTur	AN1	Z	TR.OHVPS.DataCode.OhkTur sıralı veri türü değerlerlerinden birini alır (B: Bireysel, K:Kurumsal)	Kurum adına yapılan ödemelerde K değerini alır. Kurum Kimlik Türü ve Kurum Kimlik Verisi alanlarının giilmiş olduğu çapraz olarak kontrol edilir. Ödeme Emri Rizası Nesnesindeki ÖHK Türü ile aynı olmalıdır.
> İşlem Tutarı	islTtr	Kompleks: Tutar	Z
>> Para Birimi	prBrm	AN3	Z	Para Birimi. Karekod akışında, FAST Karekod Veri Organizasyonundaki 53: (Para Birimi) alanında tanımlı Tutar verisi kullanılır.	Ödeme Emri Rizası Nesnesindeki Para Birimi verisi ile aynı olmalıdır.
>> Tutar	ttr	N1..18	Z	ÖBHS'nin ön yüzde kullanıcıdan teyit aldığı tutar. Karekod akışında, FAST Karekod Veri Organizasyonundaki 54: (Tutar) alanında tanımlı Tutar verisi kullanılır. Örneğin 1,20 TRY için tutar alanında “120” değeri iletilir	Ödeme Emri Rizası Nesnesindeki İşlem Tutarı verisi ile aynı olmalıdır. HHS işlem tutarı ödeme mesajında (Havale/FAST/PÖS) aynen taşınmak durumundadır.	Ttr

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama	HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler	FAST A01 PÖS M01 mesaj mapping
> Gönderen	gon	Kompleks: Hesap	Z
>> Unvan	unv	AN3..140	Z	Gönderen kişinin ad soyad ya da ticari unvan bilgisi.	HHS ve ÖBHS verisi tutarlı olmalıdır. ÖBHS verisi ile HHS verisinin farklılaşması durumunun ise risk değerlendirme sistemlerine girdi olarak kullanması tavsiye edilir.	GonAd
>> Hesap Numarası	hspNo	AN26	K	ÖBHS'nin ön yüzünden seçtirdiği/kullanıcıya girdiği IBAN Hesap numarası ya da Hesap Referansı alanlarından en az birinin dolu olarak gelmesi gerekmektedir.	Ödeme Emri Rizası Yanıtı Nesnesindeki Gönderen Hesap Numarası verisi ile aynı olmalıdır.	GonHesN
>> Hesap Referansı	hspRef	AN5..40	K	ÖBHS’nin aynı zamanda HBHS olduğu durumda müşteri rızası tesis edilmiş bir hesabın referansı üzerinden de ödeme başlatılabilir. GKD sonrası HHS ekranında seçilen Hesap Referansı POST işleminin yanıtında

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama	HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler	FAST A01 PÖS M01 mesaj mapping
				dönülemez ancak isteğe bağlı GET sorgusu ile dönülebilir. Hesap Numarası kullanılıyorsa Hesap Referansı kullanılmayabilir.
> Alıcı	alc	Kompleks: Hesap	Z
>> Unvan	unv	AN3..140	Z	Kolay Adres sorgusu sonucunda dönülen adres kaydı yaptırmış olan alıcının maskeli ad-soyadı veya maskeli ticari unvan bilgisidir. Kolay adres değil ise ÖBHS tarafından istek mesajında iletilen unvan bilgisidir.	YÖS’ten alıcı ad soyad bilgisi geliyorsa ve HHS'nin kontrolünden başarılı bir şekilde geçti ise HHS'nin tekrar alıcı ad soyad bilgisi için giriş yaptırmasına gerek bulunmamaktadır.	AlAd
>> Hesap Numarası	hspNo	AN26	Z	Alıcının Hesap Numarası alanıdır (IBAN). Kolay Adres sorgusunda dönülen adres kaydı yaptırmış olan alıcının maskeli IBAN bilgisidir. Kolay adres değil ise ÖBHS tarafından istek mesajında iletilen IBAN bilgisidir.	Ödeme Emri Rizası Yanıtı Nesnesindeki Alıcı Hesap Numarası verisi ile aynı olmalıdır. Kontroller başarıyla sonuçlanırsa, bilgi FAST/PÖS AlHesN alanına doğrudan aktarır ve FAST/PÖS Alan Katılımcı Kodu (AlKK) olarak Alıcı HHS Kodu kullanılır.	AlHesN

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama	HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler	FAST A01 PÖS M01 mesaj mapping
				Karekod akışında, FAST Karekod Veri Organizasyonundaki 30-01: alanında tanımlı İş Yeri IBAN verisi kullanılır.	KOLAS sorgusu sonucunda ödeme emrinde iletilen maskeli bilgi ile HHS’nin kendi ödeme emri rızası isteğinde tuttuğu KOLAS sorgusundan dönülen bilgi maskelenerek karşılaştırılır. Eğer aynı değilse uygun hata kodu dönülerek işlem sonlandırılır.
>> Kolay Adres	kolas	Kompleks: Kolas	K
>>> Kolas Türü	kolasTur	AN1	Z	Müşterinin sorgulama istediği Kolay Adres Tipi değeridir. TR.OHVPS.DataCode.KolasTur sıralı veri türü değerlerinden birini alır. Alıcı Hesap Numarası girilmediyse kullanımı zorunludur ve Kolay Adres Tipi alanıyla birlikte kullanılır.	Ödeme Emri Rizası Yanıtı Nesnesindeki Kolay Adres Tipi verisi ile aynı olmalıdır.
>>> Kolas Değeri	kolasDgr	AN7..50	Z	Müşterinin eklediği, HHS (FAST katılımcısı) tarafından doğrulanmış Kolay Adres değeridir. Alabileceği değerler BKM “Kolay Adresleme Sistemi Uygulama Kuralları” belgesinde tanımlıdır.	Ödeme Emri Rizası Yanıtı Nesnesindeki Kolay Adres Değeri verisi ile aynı olmalıdır.	FAST (KolasRef)

Alan Adı

JSON Alan

Adı

Format

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler

FAST A01

PÖS M01

mesaj mapping

Alıcı Hesap Numarası girilmediyse kullanımı zorunludur ve Kolay Adres Tipi alanıyla birlikte kullanılır.

>>> Kolas Referans

Numarası

kolasRefNo

N12

Ödemeye özel Referans Bilgisi alanıdır. Karekod işlemi değil ise zorunludur.

- Kişiden kişiye fon aktarımlarda: Gün içerisinde ÖHK için biricik olarak oluşturan referans bilgisi

- E-ticaret işlemlerinde sipariş/takip numarası/müşteri/abone numarası

- Karekod akışında, FAST Karekod

Veri Organizasyonundaki

- 62-01: alanında tanımlı Fatura Numarası

- 62-06: alanında tanımlı Müşteri Numarası

verilerinden biri kullanılır.

Ödeme Emri Rizası Nesnesindeki Referans Bilgisi verisi ile aynı olmalıdır.

FAST:

KareKod ile başlatılan işlemlerde FAST A01 mesajındaki Karekod Referansı (KrkdRef) alanına karşılık gelir. Bu durumda, FAST A01 mesajı alanları “FAST Mesaj Yapısı ve İşlem Türleri” belgesin uygun şekilde oluşturulur: KareKod (KrKd) bölümündeki Karekod Akış Türü (KrkdAksTur) ve Karekod Referansı (KrkdRef) alanları doldurulmalıdır.

Kişiden kişiye fon aktarımlarında ve e- ticaret işlemelerinde Referans Bilgisi (RefBlg) alanı doldurulur.

FAST (KrkdRef) ve (RefBlg)

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama	HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler	FAST A01 PÖS M01 mesaj mapping

>>> Kolas Hesap Türü	kolasHspTur	AN1	Z	Kolay Adres Alıcı Sorgusunda başarılı sorgu sonucunda dönülen, BKM Kolay Adresleme Sistemi Uygulama Kuralları’nda tanımlı hesap türü bilgisidir: TR.OHVPS.DataCode.KolasHspTur sırali veri değerlerinden birini alır.
> Karekod	kkod	Kompleks: Karekod	K
>> Akış Türü	aksTur	AN2	Z	Karekod Akış Türü Karekod ödemesinin hangi akışla gerçekleştirildiğini gösterir. Kolay Adresi Sistemi ile birlikte kullanılmaz. 01: FAST katılımcısından dinamik doğrulama hizmeti alınan işyeri ödemesi 02: FAST katılımcısından statik doğrulama hizmeti alınan işyeri ödemesi 03: Kişiden kişiye ödemeler	Ödeme Emri Rizası Nesnesindeki Kare Kod Akış Türü verisi ile aynı olmalıdır.	FAST: KrkdAksTur

Alan Adı

JSON Alan

Adı

Format

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler

FAST A01

PÖS M01

mesaj mapping

>> Referansı

kkodRef

AN1..12

Karekod referans numarasını gösterir.

Okunan karekodda referans değeri varsa kullanılması zorunludur.

Kolay Adresi Sistemi ile birlikte kullanılmaz.

Ödeme Emri Rizası Nesnesindeki Karekod Referansı verisi ile aynı olmalıdır.

Çevrimiçi doğrulama hizmeti alınmayan statik karekodlar için Referans numarasının bulunmadığı durumlarda HHS tarafından “NONREF” ifadesi girilir.

FAST: Karekod Referansı (KrkdRef)

>> Üretici Kodu

kkodUrtcKod

AN4

Karekod üreticisinin kodu.

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama	HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler	FAST A01 PÖS M01 mesaj mapping
> Odeme Ayrıntıları	odmAyr	Kompleks: OdemeAyr intilari	Z
>> Ödeme Kaynağı	odmKynk	AN1	Z	Ödemenin başlattığı kaynağı belirtir. TR.OHVPS.DataCode.OdemeKaynak sıralı veri değerlerinden birini alır. .	Ödeme Emri Rizası Nesnesindeki Ödeme Kaynağı verisi ile aynı olmalıdır. HHS tarafından ödeme mesajında (FAST/PÖS) aynen taşınmak durumundadır.	FAST/PÖS: OdmKynk
>> Ödeme Amacı	odmAmc	AN2	Z	TR.OHVPS.DataCode.OdemeAmaci sıralı veri değerlerinden birini alır.	Ödeme Emri Rizası Nesnesindeki Ödeme Amacı verisi ile aynı olmalıdır. HHS tarafından ödeme mesajında (FAST/PÖS) aynen taşınmak durumundadır.	FAST (OdmAmc) / PÖS (OdmAmaci)

>> Referans Bilgisi	refBlg	AN1..140	K	Ödemeye özel Referans Bilgisi alanıdır. Karekod işlemi değil ise zorunludur.		FAST (KrkdRef) ve (RefBlg)

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama	HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler	FAST A01 PÖS M01 mesaj mapping
				- Kişiden kişiye fon aktarımlarda: Gün içerisinde ÖHK için biricik olarak oluşturan referans bilgisi - E-ticaret işlemlerinde sipariş/takip numarası/müşteri/abone numarası - Karekod akışında, FAST Karekod Veri Organizasyonundaki - 62-01: alanında tanımlı Fatura Numarası - 62-06: alanında tanımlı Müşteri Numarası verilerinden biri kullanılır.
>> Açıklama	odmAcklm	AN1..50	İ	ÖBHS’nin ÖHK’dan aldığı ya da kendisinin atadığı işlem açıklaması bilgisi.		FAST/PÖS Acklm
>> ÖHK Mesaj Alanı	ohkMsj	AN1..200	İ	HHS’nin ÖHK’ya göstermek üzere ilettiği mesaj.
>> Ödeme Sistemi	odmStm	AN1	Z	TR.OHVPS.DataCode.OdemeSistemi sıralı veri değerlerinden birini alır.	Ödeme Emri Rizası Nesnesindeki Ödeme Sistemi verisi ile aynı olmalıdır.

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama	HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler	FAST A01 PÖS M01 mesaj mapping
>> Beklenen Ödeme Zamanı	bekOdmZmn	ISODateTi me	K	İşlemin yönlendirildiği ödeme sistemi PÖS ise ve PÖS işlem saatleri dışında ise işlemin yapılabileceği ilk zaman bilgisi
> ÖBHS Masraf Tutarı	obhsMsrfTtr	Kompleks: Tutar	İ
>> Para Birimi	prBrm	AN3	Z	Para birimi (TRY, USD, EUR vb.).	Ödeme Emri Rizası Nesnesindeki ÖBHS Masraf Para Birimi verisi ile aynı olmalıdır.
>> Tutar	ttr	N1..18	Z	ÖBHS’nin işlemle ilgili ÖHK’nın borçlandırılmasını belirttiği masraf tutarı. İşlem Tutarı ile aynı para biriminde olmalıdır. Örneğin 1,20 TRY için tutar alanında “120” değeri iletilir	Ödeme Emri Rizası Nesnesindeki ÖBHS Masraf Tutarı verisi ile aynı olmalıdır.
> HHS Masraf Tutarı	hhsMsrfTtr	Kompleks: Tutar	İ
>> Para Birimi	prBrm	AN3	Z	Para birimi (TRY, USD, EUR vb.).	Ödeme Emri Rizası Nesnesindeki HHS Masraf Para Birimi verisi ile aynı olmalıdır.

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama	HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler	FAST A01 PÖS M01 mesaj mapping
>> Tutar	ttr	N1..18	Z	HHS’nin işlemle ilgili ÖHK’nın borçlandırılmasını belirttiği masraf tutarı. İşlem Tutarı ile aynı para biriminde olmalıdır. Örneğin 1,20 TRY için tutar alanında “120” değeri iletilir	Ödeme Emri Rizası Nesnesindeki HHS Masraf Tutarı verisi ile aynı olmalıdır.
İşyeri Ödeme Bilgileri	isyOdmBlg	Kompleks: IsyeriOde meBilgileri	İ	İşyeri ödemelerinde kullanılabilecek alanlardır. Karekodlu işyeri ödemesi akışında bu alanlar dolu geldiği için isteğe bağlı olarak gönderilebilir. İşyeri Ödeme Bilgileri alanlarının en az birinin dolu olması durumunda yanıtta yer alır.
> İşyeri Kategori Kodu	isyKtgKod	N4	İ	İşlemin, ISO 18245:2003 uyumlu İşyeri Kategori Kodudur (Merchant Category Code, MCC). Ödeme Amacı = ‘06’ ya da ‘04’ olan ödeme işlemleri için doldurulabilir

Alan Adı

JSON Alan

Adı

Format

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

HHS tarafından ödeme emri oluşturulması sırasında yapılması gereken kontrol ve işlemler

FAST A01

PÖS M01

mesaj mapping

> Alt İşyeri Kategori

Kodu

altIsyKtgKod

İşlem alt işyerinden gerçekleştiriliyorsa, ISO 18245:2003 uyumlu İşyeri Kategori Kodudur (Merchant Category Code, MCC).

>Üye İş Yeri Tekil

Kimlik

genelUyeIsye riNo

AN8

İşyeri kayıt sisteminde kayıtlı İşyeri için BKM tarafından üretilmiş olan genel işyeri numarasıdır (GlobalMerchantId) Örnek değer ‘81630618’

BAŞARILI YANIT:

POST işleminin RESPONSE gövdesini (BODY) oluşturan “OdemeEmri” nesnesi Tablo-10’daki parametrelerden oluşur:

Tablo 10: “OdemeEmri” nesnesi

Alan Adı

JSON Alan

Adı

Format

Zorunlu / Koşullu / İsteğe bağlı

Açıklama

Riza Bilgileri

rzBlg

Kompleks: RizaBilgileri

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama
> Rıza No	rizaNo	AN1..128	Z	OdemeEmriRızası nesnesinin oluşturulması esnasında HHS kaynak sunucusu tarafından atanan biricik tanımlayıcı.
> Oluşturma Zamanı	olusZmn	ISODateTime	Z	OdemeEmriRizasi nesnesinin oluşturulma zamanı
> Xxxx Xxxxxx	rizaDrm	AN1	Z	TR.OHVPS.DataCode.RizaDurumu sıralı veri tipini değerlerinden birini alır.
Katılımcı Bilgisi	katilimciBlg	Kompleks:Katilimci Bilgisi	Z	Katılımcılara atanmış kod bilgileridir.
>Hesap Hizmeti Sağlayıcısı Kodu	hhsKod	AN4	Z	İsteğin iletildiği Hesap Hizmeti Sağlayıcısının kodudur. (Nezdinde ÖH bulunduran kuruluş kodu. Örneğin, Banka, Elektronik Para Kuruluşu ve Ödeme Kuruluşu)
> Yetkili Ödeme Hizmeti Sağlayıcısı Kodu	yosKod	AN4	Z	İsteği gönderen Yetkili Ödeme Hizmeti Sağlayıcısı (YÖS) kodudur
GKD	gkd	Kompleks: Gkd	Z
> Yetkilendirme Yöntemi	yetYntm	AN1	Z	TR.OHVPS.DataCode.GkdTur sıralı veri türü değerlerinden birini alır.
> Yönlenme Adresi	yonAdr	AN1..1024	K	Yönlendirmeli güçlü kimlik doğrulama için zorunlu.

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama
> Bildirim Adresi	bldAdr	AN1..1024	K	Ayrık güçlü kimlik doğrulama için zorunlu.
> HHS Yönlenme Adresi	hhsYonAdr	AN1..1024	K	GKD doğrulama bilgilerinin girilebilmesi için uygulamadan açılacak yönlendirme sayfasının adresi
> Yetkilendirme Tamamlanma Zamanı	yetTmmZmn	ISODateTime	Z	Yetkilendirme akışının tamamlanması gereken son zamanı gösterir. Rıza durumu Yetkilendirildi statüsüne geçene kadarki süredir.
Xxxx Xxxxxxxxx	emrBlg	Kompleks: EmirBilgileri	Z
> Ödeme Emri Numarası	odmEmriNo	AN1..128	Z	Ödeme Emri nesnesinin UID'sidir. OdemeEmrine İlişkin sorgular bu ID üzerinden yapılır.
> Odeme Emri Zaman	odmEmriZmn	ISODateTime	Z	Ödeme emrinin FAST, PÖS, havale gibi gerçekleştirileceği ilgili ödeme sistemine iletilme tarihi.
Ödeme Başlatma	odmBsltm	Kompleks: OdemeBaslatma	Z
> Kimlik	kmlk	Kompleks:Kimlik	Z
>> Kimlik Türü	kmlkTur	AN1	Z	Çerçeve sözleşme kapsamındaki ödemelerde kullanımı zorunludur. TR.OHVPS.DataCode.KimlikTur sıralı veri türü değerlerlerinden birini alır.

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama
>> Kimlik Verisi	kmlkVrs	AN1..30	Z	Çerçeve sözleşme kapsamındaki ödemelerde kullanımı zorunludur. HHS nezdinde kullanıcı doğrulamasında kullanılan tanımlayıcıdır. TR.OHVPS.DataCode.KimlikTur değerine göre uzunluk ve formatı değişir.
>> Kurum Kimlik Türü	krmKmlkTur	N1	K	Kurum adına yapılan ödemelerde ÖHK’nın altında tanımlı olduğu tüzel kişilik için kullanılan kurum kimlik türüdür. TR.OHVPS.DataCode.KurumKimlikTur sıralı veri türü değerlerlerinden birini alır.
>> Kurum Kimlik Verisi	krmKmlkVrs	AN1..30	K	Kurum adına yapılan ödemelerde ÖHK’nın altında tanımlı olduğu tüzel kişilik için kullanılan kurum kimlik verisidir. TR.OHVPS.DataCode.KurumKimlikTur değerine göre uzunluk ve formatı değişir.
>> Ödeme Hizmeti Kullanıcısı Türü	ohkTur	AN1	Z	TR.OHVPS.DataCode.OhkTur sıralı veri türü değerlerlerinden birini alır (B: Bireysel, K:Kurumsal)
> İşlem Tutarı	islTtr	Kompleks:Tutar	Z
>> Para Birimi	prBrm	AN3	Z	Para Birimi. Karekod akışında, FAST Karekod Veri Organizasyonundaki 53: (Para Birimi) alanında tanımlı Tutar verisi kullanılır.
>> Tutar	ttr	N1..18	Z	ÖBHS'nin ön yüzde kullanıcıdan teyit aldığı tutar.

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama
				Karekod akışında, FAST Karekod Veri Organizasyonundaki 54: (Tutar) alanında tanımlı Tutar verisi kullanılır. Örneğin 1,20 TRY için tutar alanında “120” değeri iletilir
> Gönderen	gon	Kompleks:Hesap	Z
>> Unvan	unv	AN3..140	Z	Gönderen kişinin ad soyad ya da ticari unvan bilgisi.
>> Hesap Numarası	hspNo	AN26	K	ÖBHS tarafından iletilip doğrulanan veya HHS ekranında seçilen Gönderen Hesap Numarası dönülür.
>> Hesap Referansı	hspRef	AN5..40	K	HHS tarafından hesap için atanan biricik tanımlıyıcıdır (uuid). YÖS bazında farklılaşması gerekmez. ÖBHS’nin aynı zamanda HBHS olduğu durumda müşteri rızası tesis edilmiş bir hesabın referansı üzerinden de ödeme başaltılabilir. GKD sonrası HHS ekranında seçilen Hesap Referansı POST işleminin yanıtında dönülemez ancak isteğe bağlı GET sorgusu ile dönülebilir. Hesap Numarası kullanılıyorsa Hesap Referansı kullanılmayabilir.
> Alıcı	alc	Kompleks: Hesap	Z
>> Unvan	unv	AN3..140	Z	Kolay Adres sorgusu sonucunda dönülen adres kaydı yaptırmış olan alıcının maskeli ad-soyadı veya maskeli ticari unvan bilgisidir. Kolas’tan dönen “account owner” alanı kullanılmalıdır. Kolay adres değil ise ÖBHS tarafından istek mesajında iletilen unvan bilgisidir.

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama

>> Hesap Numarası	hspNo	AN26	Z	Alıcının Hesap Numarası alanıdır (IBAN). Kolay Adres sorgusunda dönülen adres kaydı yaptırmış olan alıcının maskeli IBAN bilgisidir. Kolay adres değil ise ÖBHS tarafından istek mesajında iletilen IBAN bilgisidir.
>> Kolay Adres	kolas	Kompleks: Kolas	K
>>> Kolas Türü	kolasTur	AN1	Z	TR.OHVPS.DataCode.KolasTur sıralı veri türü değerlerinden birini alır. Alıcı Hesap Numarası girilmediyse kullanımı zorunludur ve Kolay Adres Tipi alanıyla birlikte kullanılır.
>>> Kolas Değeri	kolasDgr	AN7..50	Z	Müşterinin eklediği, HHS (FAST katılımcısı) tarafından doğrulanmış Kolay Adres değeridir. Alabileceği değerler BKM “Kolay Adresleme Sistemi Uygulama Kuralları” belgesinde tanımlıdır. Hesap Numarası girilmediyse kullanımı zorunludur ve Kolay Adres Tipi alanıyla birlikte kullanılır.
>>> Kolas Referans Numarası	kolasRefNo	N12	Z	Kolay Adres Alıcı Sorgusunda başarılı sorgu sonucunda dönülen, BKM Kolay Adresleme Sistemi Uygulama Kuralları’nda tanımlı KOLAS tarafından ilgili sorguya özel olarak üretilmiş referans numarasıdır.

Alan Adı	JSON Alan Adı	Format	Zorunlu / Koşullu / İsteğe bağlı	Açıklama
>>>Kolas Hesap Türü	kolasHspTur	AN1	Z	Kolay Adres Alıcı Sorgusunda başarılı sorgu sonucunda dönülen, BKM Kolay Adresleme Sistemi Uygulama Kuralları’nda tanımlı hesap türü bilgisidir. TR.OHVPS.DataCode.KolasHspTur sıralı veri değerlerinden birini alır.
> Karekod	kkod	Kompleks: Karekod	K
>> Akış Türü	aksTur	AN2	Z	TR.OHVPS.DataCode.KareKodAksTur sıralı veri değerlerinden birini alır. Kolay Adresi Sistemi ile birlikte kullanılmaz.
>> Referansı	kkodRef	AN1..12	K	Karekod referans numarasını gösterir.
>> Üretici Kodu	kkodUrtcKod	AN4	Z	Karekod üreticisinin kodu. Ödeme Hizmeti Sağlayıcıları ve TCMB tarafından uygun görülen ödeme sistemi işleticisi TR Karekod üretebilmek için BKM’ye kayıt başvurusu yaparak karekod üretici kodu alabileceklerdir. Bankalar EFT kodlarını kullanacak olup ayrıca kayıt yaptırmalarına gerek bulunmamaktadır. 4 haneden kısa değerlerin sol tarafı ’0’ karakteri ile tamamlanmalıdır.
> Odeme Ayrıntıları	odmAyr	Kompleks: OdemeAyrintilari	Z

Document Metadata

Table of Contents

İçindekiler

Document Metadata