-
Güvenlik Platformu
Güvenlik Platformu
Cirom Güvende Genel Kavram
Bu dokümanda Garanti BBVA Fraud Modülü entegrasyonu yapacak işyerleri için gereksinimler detaylandırılmıştır.
Dokümandaki bilgilere ek olarak aşağıdaki link üzerinden de kullanılan endpointler, request/response alan isimleri ve tipleri hata kodları gibi bilgilere ulaşılabilir ve örnek post isteği gönderilebilir.
Test Ortamı
Test ortam adresi: atalantegwtest.garanti.com.tr
Swagger: https://atalantegwtest.garanti.com.tr/swagger-ui.html
| Başlık | Değer |
|---|---|
| MerchantId | 7000679 |
| Password | 123qweASD/ |
| MerchantId | 3424113 |
| Password | 123qweASD/ |
Üretim Ortamı
Prod ortam adresi: https://atalantegw.garanti.com.tr
Garanti Bankası Güvenlik Platformu Teknik Entegrasyon Dokümanı
Tam yetkili kullanıcı ekranda yer alan "Şifre" input alanlarına ilgili değerlerin giriş yapılması suretiyle işyeri sistemi ve Atalante servisleri arasındaki mesajlaşma esnasında encoded hash değeri oluşturulurken kullanılacak şifreyi belirler.
Tam yetkili kullanıcı Fraud Modülüne ilk eriştiğinde bu değer sistemde default olarak tutulmaktadır.
Kullanıcı belirlediği şifreyi "Şifre", "Şifre Tekrar" alanlarına girerek ve ekranda yer alan captchadaki değerleri ilgili alan yazarak KAYDET butonuna basar ve şifre resetlenir.
Request Header Tag'i ve İçeriği
Garanti BBVA Fraud Modülü’nde istek mesajları "requestHeader" header tag’i ve içeriği ile gönderilir. "requestHeader" tag’i altında gönderilmesi gereken alanlar ve içerikleri aşağıdaki tabloda detaylandırılmıştır.
| Veri Alanı | Zorunluluk | Açıklama | Uzunluk/Format/Değerler |
|---|---|---|---|
| gvpsMerchantNum | Zorunlu | İlişkilendirilmiş Garanti BBVA işyeri numarasının gönderildiği alandır. | İşyerine Garanti BBVA tarafından tahsis edilen işyeri numarası değeri bu alanda gönderilir. |
| hashData | Zorunlu | Gönderilen isteğin güvenliğini sağlamak için kullanılacak bilgi olacaktır.Bu bilgi ile izin verilen işyeri dışında sisteme işlem gönderilmesi engellenecektir. | “hashData” değerinin hesaplanma yöntemi detaylandırılmıştır. |
| orderId | Zorunlu | Gönderilecek işlemin sipariş numarasının gönderildiği alandır. | |
| transactionType | Zorunlu | İşyerinin provizyon gerçekleştireceği işlem tipi bilgisi bu alanda gönderilmelidir. Tablo 6’da alanın alabileceği değerler yer almaktadır. | |
| uniqueId | Zorunlu | Cihaz ID belirme sürecinde işyerine dönülen Unique ID değeridir. | PageLoad süreci bittiğinde elde edilen tekil değer bu alanda gönderilir. 24 karakter uzunluğunda, alfanumeriktir. |
Örnek request header mesaj parçası aşağıda verilmiştir.
\"requestHeader\": { \n \"gvpsMerchantNum\": 100018660,\n \"hashData\": \"52946e0693e3ae2679194a43bbf6baf220369e33\", \n \"orderId\": \"asdqwer1234567\",\n \"transactionType\": \"sales\",\n \"uniqueId\": \"Wjk5NDVGRTE2Q0ZGNDVENTgw\"\n}
HashData Alanının Hesaplanması
Dokümanda yer alan hash hesaplamalarının nasıl yapılacağı bu başlık altında anlatılmaktadır. “hashData” değeri iki aşamalı olarak hesaplanmaktadır.
HashData= SHA1(MerchantNum&TransactionType&OrderID&UniqeuID&HashedPassword)
- MerchantNum: Üye işyeri numarasıdır. İşyeri numarasının kaç hane olduğu farketmeksizin olduğu şekilde hash data içerisine yazılacaktır.
- TransactionType: İşlem tipi bilgisidir.
- OrderId: İşlem sipariş numarası bilgisidir.
- UniqueId: Cihaz ID belirme sürecinde işyerine dönülen Unique ID bilgisidir.
- HashedPassword: Hashli şifre bilgisidir. Hashli şifre bilgisi aşağıdaki şekilde hesaplanmaktadır.
HashedPassword: UPPERCASE (SHA1 (Password&MerchantNum))
- Password: Üye işyeri şifre bilgisidir.
- MerchantNum: Üye işyeri numarasıdır. İşyeri numarasının 8 hane olarak hesaplamaya dahil edilmesi gerekmektedir.
8 karakterden az olan isyeri numaraları için numaranın başına 8 haneye tamamlayacak şekilde 0 eklenmelidir.
Örnek 1;
İşyeri numarası: 123456
Hesaplamaya eklenecek işyeri numarası: 00123456
Örnek 2;
İşyeri numarası: 1234567
Hesaplamaya eklenecek işyeri numarası: 01234567
8 karakter olan isyeri numaraları için işyeri numarasının başına ekleme yapılmadan olduğu gibi yazılacaktır.
Örnek;
İşyeri numarası: 12345678
Hesaplamaya eklenecek işyeri numarası: 12345678
8 karakterden fazla olan isyeri numaraları için işyeri numarası 8 hane olacak şekilde, işyeri numarasının sağından 1 ya da daha fazla karakter kırpılarak hash hesabına dahil edilecektir.
Örnek 1;
İşyeri numarası: 123456780
Hesaplamaya eklenecek işyeri numarası: 12345678
Örnek 2;
İşyeri numarası: 1234567801
Hesaplamaya eklenecek işyeri numarası: 12345678
MerchantNum ve Password değerleri için E-Ticaret Destek ETicaretDestek@garantibbva.com.tr ekibimizden bilgi alabilirsiniz.
Örnek Hashed Password Hesaplamasi
Password: password1@\n\nMerchantNum: 100018660\nHashedPassword: UPPERCASE (SHA1 (Password&MerchantNum)) Hashed Password: UPPERCASE (SHA1 (password1@10001866))=\nE12B51570844121AD09279F18E3D76EEC04190A4\n\nMerchantNum: 100018660 TransactionType: sales OrderId: 53451232223\nUniqueId: gpIJ0Oj8UEyUZjywrqt0JA==\n\nHashedPassword: E12B51570844121AD09279F18E3D76EEC04190A4\n\nHashData= SHA1(MerchantNum&TransactionType&OrderID&UniqeuID&HashedPassword)\n\nHashData= SHA1(100018660sales53451232223gpIJ0Oj8UEyUZjywrqt0JA== E12B51570844121AD09279F18E3D76EEC04190A4)=\nc27da1211a3632a59bc37779824facc83a81b4f2
Skor Sorgulama İşyeri Sonuç İşlemi
Skor isteğinde işyerine dönülen cevap sonrasında işyerinin son durum bilgisini fraud modülü ile paylaşması gerekmektedir.
Eğer işlem provizyona devam ettiriliyorsa provizyon bilgisinin de işlem geri bildiriminde olması gerekmektedir.
İşyeri tarafından oluşturulacak mesaj yapısının JSON mesaj yapısı formatında hazırlanıp https://atalantegwtest.garanti.com.tr/scoreResult URL’ine isteklerin gelmesi sağlanır.
Skor sorgulama isteği örnek mesaj yapısı aşağıda belirtilmiştir.
TEST URL: https://atalantegwtest.garanti.com.tr/scoreResult \nPROD : https://atalantegw.garanti.com.tr/scoreResult\n\nHeaders:\ncontent-type: application/json;charset=UTF-8 \nversion: v1
{\n \"requestHeader\": {\n \"uniqueId\": \"N0Q0NTI0NjRCQTY1NDBCNThB\",\n \"relatedGVPSMerhcant\": 123456,\n \"hashData\": \"B29C2D40A38318D36F3227E9D2C986FC4C5A89C3\",\n \"orderId\": \"6E6FA33577034E858A56691B5BC55602\",\n \"transactionType\": \"sales\"\n },\n \"merchantDecision\": \"01\",\n \"responseCode\": \"00\",\n \"reasonCode\": \"00\"\n}
"requestHeader" tagı altında gönderilecek içeriğin bilgisine Request Header Tagı ve İçeriği başlığı altında detaylandırılmıştır. İstek mesajı skorlama isteğinde dönülen unique id numarası ile yapılacaktır.
| Veri Alanı | Açıklama | Uzunluk/Format/Değerler |
|---|---|---|
| merchantDecision | İşyerinin provizyon kararı bu alanda gönderilmelidir. | 2 byte’lık bir data bu alanda gelecektir.01– riskli görüldüğü için devam ettirilmedi02 - Provizyona devam ettirildi |
| responseCode | Provizyondan dönen cevap kodu bu alanda gönderilmelidir. | |
| reasonCode | Provizyondan dönen detaycevap kodu bu alanda gönderilmelidir. |
Skor Sorgulama İşyeri Sonuç Cevabı
İşyerine dönülen cevap mesajında işlemin sisteme başarılı bir şekilde ulaşıp ulaşmadığı bilgisi bulunur.
| Veri Alanı | Açıklama | Uzunluk/Format/Değerler |
|---|---|---|
| errorType | Error tipi bilgisinin iletildiği alandır. | |
| returnCode | İstek cevabına ait sonuç kodunun dönüleceği alandır. | 00 OK01 Authentication Error 03 Skorlamamodülühatası (işlemi skorlama modülüne iletmekte sıkıntı yaşadıysak)04 Input DataError08 Daha önceden zaten skor sonuç bilgisigönderildi09 İlgili işlem bulunamadı 99 General Error |
| responseMsg | Hatalı geri dönüşlerde hata koduna ait cevap metninin dönüleceği alandır. | 00 OK 01 Authentication Error 03 Skorlama modülü hatası(işlemi skorlama modülüne iletmektesıkıntı yaşadıysak)04 Input Data Error08 Daha önceden zaten skor sonuç bilgisigönderildi09 İlgili işlembulunamadı99 General Error |
Kod Örnekleri
Aşağıda, çeşitli yazılım dilleri kullanılarak yazılmış özel kod örneklerinin linkleri verilmiştir. Tercih ettiğiniz programlama diline ait link üzerinden, önceden belirlenmiş değerlerle yazılmış olan kodları detaylı bir şekilde inceleyebilirsiniz.
Bu örnekler, ilgili işlem tipini içeren kodları içermektedir ve farklı dillerde yazıldığı için çeşitli yaklaşımları ve pratikleri de gözlemleyebilirsiniz. Bu sayede tercih ettiğiniz programlama diline dair daha iyi anlaşılır ve özgün örneklerle çalışma imkanı bulabilirsiniz.
C# Kod Örnekleri için tıklayınız.
VB.Net Kod Örnekleri için tıklayınız.
Java Kod Örnekleri için tıklayınız.
PHP Kod Örnekleri için tıklayınız.
Unutmayın ki bu örnekler ön tanımlı değerlerle yazılmıştır ve gerçek projelerde kullanımı için gerekli uyarlama ve güvenlik önlemleri almanız gerekebilir.
Ülke - İl - İlçe Kodları
Ülke kodları listesine bu sayfadan ulaşabilirsiniz.
İl kodları listesine bu sayfadan ulaşabilirsiniz.
İlçe kodları listesine bu sayfadan ulaşabilirsiniz.
Ürün Kategori Kodları
Ürün kategori kodları listesine bu sayfadan ulaşabilirsiniz.
Transaction Type Değerleri
Transaction type değerleri listesine bu sayfadan ulaşabilirsiniz.
Test Kartları
Test kartları listesine bu sayfadan ulaşabilirsiniz.
