-
Sanal Pos
Security Platform
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
Score Enquiry Workplace Result Process
After the response returned to the workplace in the score request, the workplace must share the latest status information with the fraud module.
If the transaction is continued for authorisation, the authorisation information must also be in the transaction feedback.
The message structure to be created by the workplace is prepared in JSON message structure format and requests are sent to https://atalantegwtest.garanti.com.tr/scoreResult URL.
The score query request sample message structure is given below.
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}
The information of the content to be sent under the "requestHeader" tag is detailed under Request Header Tag and Content. The request message will be made with the unique id number returned in the scoring request.
| Data Field | Description | Length/Format/Values |
|---|---|---|
| merchantDecision | Provision decision of the workplace must be sent in this field. | A 2 byte data will come in this field.01- not continued because it is considered risky02 - Provision continued |
| responseCode | The response code returned from the provision must be sent in this field. | |
| reasonCode | The detail response code returned from the provision must be sent in this field. |
Score Enquiry Workplace Result Answer
In the reply message returned to the workplace, there is information about whether the transaction has successfully reached the system.
| Data Field | Description | Length/Format/Values |
|---|---|---|
| errorType | This is the field where error type information is transmitted. | |
| returnCode | This is the field where the result code of the request response will be returned. | 00 OK01 Authentication Error 03 Scoring module error (if we had trouble transmitting the transaction to the scoring module)04 Input DataError08 Already sent score result information09 Related transaction not found 99 General Error |
| responseMsg | This is the field where the answer text of the error code will be returned in erroneous returns. | 00 OK 01 Authentication Error 03 Scoring module error (if we had trouble transmitting the transaction to the scoring module)04 Input Data Error08 Already sent score result information09 Related transaction could not be found99 General Error |
Code Examples
Below are links to custom code examples written in various programming languages. You can examine the codes written with predetermined values in detail through the link of your preferred programming language.
These examples contain the codes containing the relevant operation type and since they are written in different languages, you can also observe various approaches and practices. In this way, you can find the opportunity to work with better understandable and original examples of your preferred programming language.
Click for C# Code Examples.
Click for VB.Net Code Examples.
Click for Java Code Examples..
Click here for PHP Code Examples.
Please note that these examples are written with predefined values and you may need to take necessary adaptation and security measures for use in real projects.
Country - Province - District Codes
You can access the list of country codes from this page..
You can access the list of province codes from this page.
You can access the list of district codes from this page.
Product Category Codes
You can access the list of product category codes from this page.
Transaction Type Values
You can access the list of transaction type values from this page.
Test Cards
You can find the list of test cards on this page.
