-
Kart Saklama
Kart Saklama
Kart Saklama Genel Kavram
Üye iş yerleri token alma servislerini kullanarak, ödeme oluşturmadan işlem içerisinde gönderdikleri müşteri kart bilgilerinin Garanti Bankası sunucularında güvenli bir şekilde şifrelenmesini sağlayarak unique bir token elde ederler. Servis çağrımı esnasında token alma işlemi yapılan kart için validasyon kontrolleri yapılır. Eğer kart provizyon almaya uygun bir kart ise işlem sonucunda üretilen token bilgisi cevap mesajında üye işyerine dönülür.
Garanti bankası kartları dışındaki diğer banka kartları ile gönderilen token alma işlemlerinde kart validasyonu için her token alma işleminde sistem tarafından 0,11 TL tutarında bir satış işlemi yapılır. Eğer satış işlemi başarılı olur ise kart için bir token değeri üretilir ve 0,11 TL tutarındaki satış işlemi otomatik olarak iptal edilir. Bu işlem kart hamilinin e kstresinde görüntülenmez.
Üye iş yerleri servis cevabında dönen token bilgisini müşteri verileri ile ilişkilendirmek ( örneğin kayıt numarası, müşteri numarası vs.) sureti ile daha sonra ödeme işlemlerinde kullanmak için saklamalıdır.
Garanti Bankası sunucularında işlem içerisinde gönderilen kart bilgileri ya da müşteri bilgileri yerine üretilen token bilgisi üye iş yeri ile ilişkili bir biçimde saklanır. Tokenların yönetimi ve kullanımı üye iş yerine aittir.
Test Ortamı
Kart Saklama ve Switch servislerini test etmek için kullanılacak TEST BASE URL aşağıdaki gibidir:
TEST BASE URL: https://gbtaksimtunel-integration.garanti.com.tr/
Not: Bu TEST BASE URL, Garanti Bankası tarafından sunulan sanal ortamı temsil eder ve gerçek işlemler yerine test amaçlı kullanılması için oluşturulmuştur. Bu ortamda yapılan işlemler, canlı ortamdaki gibi gerçek finansal etkiler doğurmaz ve sadece test senaryoları üzerinden işlemektedir.
Test ortamı, farklı senaryoları ve hata durumlarını simüle ederek uygulamanın performansını ve güvenilirliğini test etmeyi sağlar. Ayrıca, API isteklerinin ve cevaplarının doğru şekilde işlendiğini doğrulamak için kullanılabilir.
Testler sırasında olası hata durumlarına karşı nasıl tepki verileceği, hataların nasıl ele alınacağı ve sistemin doğru şekilde çalıştığından emin olunmalıdır. Testler, güvenlik ve uyumluluk açısından da önem taşır ve canlı ortama geçiş öncesinde başarılı bir test aşaması gerçekleştirilmelidir.
Test ortamındaki hataların geçici olabileceği unutulmamalıdır. Geliştirme ekibi, olası hataların sıklıkla tekrarlanması durumunda ETicaretDestek@garantibbva.com.tr destek birimleriyle iletişime geçmeyi tercih etmelidir. Bu şekilde, sorunlar daha hızlı ve etkili bir şekilde çözülerek test sürecinin verimli bir şekilde ilerlemesi sağlanacaktır. Başarılı testler, uygulamanın ve sistemlerin güvenli ve sorunsuz bir şekilde canlı ortama geçişine büyük katkı sağlar.
Test ortamında API isteklerinde gönderilmesi için aşağıdaki bilgiler kullanılabilir. Bu değerler, tüm istek tiplerinde kullanılacaktır:
| Başlık | Değer |
|---|---|
| Switch ID: | CC82C381E078482AB328943FCCB7100C |
| Switch Şifresi: | 123asdASD@ |
Bu bilgiler, Kart Saklama ve Switch API'larını test etmek için kullanılacak olan kimlik doğrulama bilgileridir. Testlerin başarıyla gerçekleştirilmesi ve doğru sonuçlar alınabilmesi için bu bilgilerin doğru bir şekilde kullanılmasına özen gösterilmelidir. API isteklerinin bu kimlik bilgileriyle yapıldığından emin olmak, testlerin güvenilirliği ve başarısı için önemlidir.
Üretim Ortamı (Üye İş Yeri Credential’larının Alınması)
Üye iş yerinin üretim ortamında gerçek verilerle istek göndermek için, test ortamında entegrasyon tamamlandıktan sonra üye iş yerinin Garanti Sanalpos terminal numarasını ETicaretDestek@garantibbva.com.tr adresine ileterek Switch ID değerini elde etmesi gerekmektedir.
Elde edilen Switch ID değerine istinaden API isteklerinde güvenlik amaçlı oluşturulan hash verisinin hesaplanması gerekmektedir. Bu hash verisi hesabında üye iş yerinin Switch Şifresi de yer almalıdır. Hash hesabıyla ilgili detaylar ilerleyen kısımlarda açıklanacaktır.
Üye iş yerinin Switch Şifresi, üye iş yerinin yönetim ekranlarında bulunan Parola Güncelleme menüsü altından oluşturulmalıdır. Bu işlem, üye iş yeri admin kullanıcısı tarafından gerçekleştirilir.
Switch Şifresi oluşturulması hakkında detaylı bilgiye "Parola Güncelleme" başlığı altından ulaşılabilir. Bu şekilde, üye iş yerleri güvenli bir şekilde gerçek verilerle API isteklerini gerçekleştirebilir ve GarantiBBVA Switch entegrasyonunu başarıyla tamamlayabilirler.
API İstek ve Cevapları Header Bilgisi
Kart saklama ve Switch sistemine atılacak bütün JSON API isteklerinde Request Header alanının eksiksiz olarak gönderilmesi gerekmektedir. Bu alanlar ile ilgili işlemin içerisinde yer alan alanların kontrolü yapılır ve gönderilen datanın valid olup olmadığı kontrol edilir. Bahsi geçen isteklerin hepsinin JSON API response bilgisinde response header alanı dönülecektir. Atılan bütün JSON API isteklerinin Content-Type bilgisi application/json tipinde olmalıdır. Yine atılan bütün JSON API isteklerinin encodingi UTF-8 formatında olmalıdır.
Request Header tag’ı ve altında gönderilecek parametreler aşağıdaki gibidir:
| Alan | Tip | Zorunlu | Uzunluk | Açıklama |
|---|---|---|---|---|
| requestId | String | Evet | Max 36 karakter | Her işlem için üretilen unique ID değeridir. |
| swtId | String | Evet | Max 36 karakter | İşlemi gerçekleştiren işyeri yada firma adına tanımlanmış switch ID değerinin gönderildiği alandır.Testlerde, üst segmentte iletilen swtId kullanılabilir. Prod ortamı için işyerine tanımlanmış swtId kullanılmalıdır. |
| timestamp | String | Evet | - | İşlem zamanı bu alanda gönderilir. |
| userId | String | Evet | Max 36 karakter | İşlemi gerçekleştiren kullanıcının ID değerinin gönderildiği alandır. Herhangi bir data gönderilebilir ama işyerine özel bir değer olması önerilir. Bu data ile amaç, gönderilen isteğin hangi kişi ya da sistem tarafından ayrıştırılmasını sağlamaktır. |
| hashedData | String | Evet | - | İşyeri tarafından JSON API Request Hash Hesaplama Örneği başlığı altında verilen kriterlere göre hash hesaplaması yapılarak üretilen değer bu alanda yollanılır. |
Response Header tag’ı ve altında dönülecek parametreler aşağıdaki gibidir:
| Alan | Tip | Açıklama |
|---|---|---|
| requestId | String | Her işlem için üretilen unique ID değeridir. Request header’ında gönderilen alan ile aynı değeri tutacaktır. |
| swtId | String | İşlemi gerçekleştiren işyeri yada firma adına tanımlanmış switch ID değerinin gönderildiği alandır. Request header’ında gönderilen alan ile aynı değeri tutacaktır. |
| timestamp | Timestamp | İşlem zamanı bu alanda gönderilir. Buradaki değer Kart Saklama ve Switch sisteminde işlemin geçtiği timestamp değeridir. |
| userId | String | İşlemi gerçekleştiren kullanıcının ID değerinin gönderildiği alandır. Request header’ında gönderilen alan ile aynı değeri tutacaktır. |
| hashedData | String | JSON API Response Hash Hesaplama Örneği başlığı altında verilen kriterlere göre bir hash hesaplaması yapılarak üretilen değer bu alanda yollanılır. |
Bütün JSON API response’larında header alanına ek olarak, header alanı dışında errorMap isimli, request’te gönderilen alanların datasal hata içerip içermediğini belirtilen bir Map dönmektedir.
| Alan | Tip | Açıklama |
|---|---|---|
| errorMap | Map<String, String> | İstekte gönderilen alanların datasal hata içerip içermediğini iletir. |
Servis Çağrıları için Hash Hesaplama
Aşağıda, Garanti Switch API'larına gönderilecek örnek bir istek mesajının header tag'ı ve alanları açıklanmaktadır:
\"header\": {\n \"requestId\": \"unique_request_id\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"userId\": \"your_user_id\",\n \"timestamp\": \"15032021151020\",\n \"hashedData\": \"Buraya hesaplanan hash değeri gelmelidir\"\n}
HashedData Hesaplama:
"HashedData" alanı, güvenlik amacıyla API isteğinin bütünlüğünü doğrulamak için kullanılır. Bu alanın hesaplanması için aşağıdaki adımlar izlenir:
- Concatenate: Öncelikle, "requestId", "swtId", "userId" ve "timestamp" ve "swtPassword" değerleri birleştirilir.
- Hashing: Daha sonra, bu birleştirilmiş değer, SHA256 algoritması kullanılarak bir hash değerine dönüştürülür.
- Uppercase: Son olarak, elde edilen hash değeri büyük harfe çevrilir.
Örnek Veri ve Hesaplama
requestId = \"unique_request_id\"\nswtId = \"CC82C381E078482AB328943FCCB7100C\"\nuserId = \"your_user_id\"\ntimestamp = \"15032021151020\"\nswtPassword = \"123asdASD@\"\n\nConcatenatedValue = \"unique_request_idCC82C381E078482AB328943FCCB7100Cyour_user_id15032021151020123asdASD@\"\nHashedData = UPPERCASE(SHA256(ConcatenatedValue))\nHashedData = \"1188B66CDFDDBAAD848CDFCC0749E1B41BC0AD8BD7F9D6004E45517400095933\"\n
Hesaplanmış Son Header Verisi Örneği
\"header\": {\n \"requestId\": \"unique_request_id\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"userId\": \"your_user_id\",\n \"timestamp\": \"15032021151020\",\n \"hashedData\": \"1188B66CDFDDBAAD848CDFCC0749E1B41BC0AD8BD7F9D6004E45517400095933\"\n}
Servis Cevapları için Hash Hesaplama
İşlem sonuçlarında dönen cevap içerisinde yer alan hashedData parametresini doğrulamak için örnek response header bilgisi ve bu bilgiye ait hash hesaplama yöntemi aşağıdaki gibidir:
Örnek Response Header
\"header\": {\n \"requestId\": \"ba0e96080c7b4216847ef71197d4ad06\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"returnCode\": \"00\",\n \"reasonCode\": \"00\",\n \"message\": \"Başarılı\",\n \"timestamp\": 1615734734018,\n \"hashedData\": \"937D994CF3CB41912FE90595FD431197DB809B9C968B4C9F652B637434BCAAA5\"\n}
HashedData Hesaplama:
Response'da yer alan "timestamp" alanı Unix Timestamp olarak dönmektedir, ancak hash hesabı için bu değerin String formatında kullanılması gerekmektedir. Bu nedenle, Unix Timestamp değeri, String formatına dönüştürülmelidir.
HashedData hesaplama işlemi için aşağıdaki adımlar izlenir:
- Concatenate: "requestId", "swtId", "returnCode", "reasonCode", "message" ve "timestamp.getTime()" değerleri birleştirilir. "timestamp.getTime()" ile Unix Timestamp değeri String formatına dönüştürülür.
- Hashing: Birleştirilmiş bu değer, SHA256 algoritması kullanılarak bir hash değerine dönüştürülür.
- Uppercase: Son olarak, elde edilen hash değeri büyük harfe çevrilir.
Örnek HashedData Hesaplaması:
requestId = \"ba0e96080c7b4216847ef71197d4ad06\"\nswtId = \"CC82C381E078482AB328943FCCB7100C\"\nreturnCode = \"00\"\nreasonCode = \"00\"\nmessage = \"Başarılı\"\ntimestamp = 1615734734018 (Unix Timestamp değeri)\nSwitch Password = \"123asdASD@\"\n\nHashedData hesaplaması için bu değerler kullanılırsa:\n\nConcatenatedValue = \"ba0e96080c7b4216847ef71197d4ad06CC82C381E078482AB328943FCCB7100C0000Başarılı1615734734018123asdASD@\"\nHashedData = UPPERCASE(SHA256(ConcatenatedValue))\nHashedData = \"937D994CF3CB41912FE90595FD431197DB809B9C968B4C9F652B637434BCAAA5\"\n
HashedData değeri, örnek response header'da belirtilen değerle aynıdır. Bu şekilde, API cevaplarında yer alan hashedData değerinin doğruluğu doğrulanabilir ve veri bütünlüğü sağlanmış olur.
Token Sorgulama
Token alma isteği sonucunda üretilen tokenların sorgulanması istendiğinde kullanılan servistir.
PROD Ortamı:\nhttps://kartsaklamabackend.garanti.com.tr/api/token/inquiry\n\nTEST Ortamı:\nhttps://gbtaksimtunel-integration.garanti.com.tr/api/token/inquiry
Servise Gönderilmesi Gereken Parametreler
Token sorgulama servisinde Request Header tag’ına ek olarak gönderilmesi gereken parametreler aşağıdaki şekildedir:
| Alan | Tip | Zorunluluk | Açıklama |
|---|---|---|---|
| originalRequestId | String | Evet | İlk token alma isteğinde atılan işlemin requestId bilgisidir. |
Servisten Dönen Parametreler
Token sorgulama servisinden response header alanına ek olarak dönen parametreler aşağıdaki şekildedir:
| Alan | Tip | Açıklama |
|---|---|---|
| token | String | İşlem sonucunda üretilen token ID değeri. Bu değer üye işyeri tarafında müşteri ile ilişkili olarak ödeme işlemlerinde gönderilmek üzere saklanmalıdır. |
| binNumber | String | İşlemde kullanılan kartın bin numarası(ilk 6 hanesi). |
| bankId | String | İşlemde kullanılan kartın kayıtlı olduğu bankanın ID değeri. |
| maskedNumber | String | İşlemde kullanılan kartın maskeli hali. |
| bankName | String | İşlemde kullanılan kartın kayıtlı olduğu bankanın adı. |
Örnek İstek Mesajı
Token sorgulama örnek istek ve cevabı aşağıdaki gibidir.
{\n \"originalRequestId\": \"2de17de4f1d342a39954edf1b2cb0010\",\n \"header\": {\n \"requestId\": \"779666b4b8a3496d9ed20df34ff5e959\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"userId\": \"your_user_id\",\n \"hashedData\": \"FE773C723CE7C76EA2478EBF1D67C99FC3EE7BA7E501B520F1A1A2ACA9B52C9 6\",\n \"timestamp\": \"2021-03-15T21:49:40.821Z\"\n }\n}
Örnek Cevap Mesajı
{\n \"card\": {\n \"token\": \"228F2BF24B6F46F2B740C54529BC7B5E\",\n \"binNumber\": \"554960\",\n \"bankId\": \"62\",\n \"maskedNumber\": \"554960******7017\",\n \"bankName\": \"T. GARANTİ BANKASI A.Ş.\"\n },\n \"header\": {\n \"requestId\": \"779666b4b8a3496d9ed20df34ff5e959\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"returnCode\": \"00\",\n \"reasonCode\": \"00\",\n \"message\": \"Başarılı\",\n \"timestamp\": 1615844982278,\n \"hashedData\": \"1034DE3502A7E90284101F102E73DE6A2B0BD6C330B98EA26C37D16CBD943FC9\"\n }\n}
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.
Test Kartları
Test kartları listesine bu sayfadan ulaşabilirsiniz.
