-
Switch
Kart Saklama ve Switch İşlemleri Genel Kavramlar
Kart Saklama ve Switch Uygulaması, işletmelerin online ödemelerde güvenli ve etkili bir şekilde yönetimini sağlayan profesyonel bir API seti sunmaktadır. Bu özel API seti, iş yerlerine müşteri kart bilgilerini güvenle saklama imkanı sunarken, aynı zamanda bu saklanan kart verileri veya açık kart bilgileri üzerinden birden fazla banka Sanalpos'una ödeme emri başlatma olanağı sağlamaktadır.
Switch Yönetim ekranları sayesinde işletmeler, kolaylıkla iptal, iade ve ön otorizasyon kapama gibi işlemleri gerçekleştirerek ödeme süreçlerini etkin bir şekilde yönetebilirler. Ayrıca uygulama, işlem ve sipariş durumlarını anlık olarak takip edebilme imkanı sunarak işletmelere güncel verilerle bilgi sağlamaktadır.
Kart Saklama ve Switch Uygulaması, müşteri verilerinin güvenliği ve ödeme süreçlerinin sorunsuz işleyişi üzerinde odaklanarak, işletmelere güvenilir bir ödeme altyapısı sunmayı amaçlamaktadır. Profesyonel ve güvenilir hizmet anlayışıyla, işletmelerin ödeme kabul etme süreçlerini kolaylaştırmak ve müşterilere kesintisiz bir ödeme deneyimi sunmak için tasarlanmıştır.
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.
3D Servis Çağrıları için Hash Hesaplama
3D ile ödeme yaparken gönderilmesi gereken alanlardan biri hashedData isimli alandır. Bu alanda gönderilen 3D isteğinin içeriğinde yer alan belli başlı alanlar kullanılarak üretilen hash değeri beslenmelidir. Hash değeri hesaplamasında istek içerisinde gönderilen aşağıdaki parametrelerin yan yana String olarak concat edilip, Switch kullanıcısı için üretilen şifre değerinin hesaplamaya konulması gerekmektedir. Elde edilen son String değeri SHA256 algoritması kullanılarak hash hesabı için kullanılır. Hash sonucunda üretilen String büyük harflere çevrilip hashedData alanına beslenir. Yöntem ve örnek aşağıdaki gibidir :
hashedData = UPPERCASE(SHA256(swtId & orderId & txnType & txnAmount &\ntxnInstallmentCount & successUrl & failureUrl & txnTimestamp & txnCurrencyCode\n& switchPassword))\n\nÖrnek Data :\nswtid : CC82C381E078482AB328943FCCB7100C\norderId : unique_order_id\ntxnType : sales\ntxnAmount : 1.45\nxnInstallmentCount : 0\nsuccessUrl : https://garantibbvapos.com.tr/destek/postback.aspx\nfailureUrl : https://garantibbvapos.com.tr/destek/postback.aspx\ntxnTimestamp : 18032021222930\ntxnCurrencyCode : 949\nswitchPassword : 123asdASD@\n\nhashedData = UPPERCASE(SHA256(CC82C381E078482AB328943FCCB7100Cunique_order_idsales1.450\nhttps://garantibbvapos.com.tr/destek/postback.aspxhttps://garantibbvapos.com.tr/destek/postback.aspx18032021222930949123asdASD@))\n\nhashedData = 896F569528570C0735D319F9EA16B465B89EDC2E91362A28DD6D130FFCA728C8
3D Servis Cevapları için Hash Hesaplama
3D ile ödeme alındıktan sonra merchanta gönderilen cevap formunda da hashedData isimli alan yer alacaktır. Merchant, 3D cevap formunda dönülen alanlardan aşağıdakilerini kullanarak hashedData alanındaki değeri üretmek süreti ile gelen datanın validitesini kontrol edebilir. Response hashi de yine Request hash’i hesabında olduğu gibi bazı alanların yan yana String olarak concat edilip, Switch kullanıcı şifresini de String’in sonuna concat edip SHA256 algoritması ile hashini alıp, büyük harflere çevirerek elde edilebilir. Yöntem ve örnek aşağıdaki gibidir:
hashedData = UPPERCASE(SHA256(requestId & swtId & returnCode & reasonCode &\nmessage & switchPassword))\n\nÖrnek Data :\nrequestId : 01032021191812\nswtId : CC82C381E078482AB328943FCCB7100C\nreturnCode : 00\nreasonCode : 00\nmessage : Başarılı\nswitchPassword : 123asdASD@\n\nÖrnek Data ile 3D Response Hash Hesabı:\n\nhashedData = UPPERCASE(SHA256(01032021191812CC82C381E078482AB328943FCCB7100C0000B\naşarılı123asdASD@))\n\nhashedData = 5A9AAE6D755B8662042C02A2645108F4998EAFA2E8DF52121A259ADBF26877E0
Servis Cevapları ErrorMap İçeriği
API isteklerinde gönderilen alanların Kart Saklama ve Switch sistemine uygun olmadığı durumlarda, API'nin response'unda "header" bölümüne ek olarak "errorMap" isimli bir Map<String, String> dönecektir. Bu "errorMap" içerisinde, hangi datanın bozuk olduğu ve datanın neden bozuk olduğu bilgisi yer alacaktır. Bu sayede, ilgili alanların düzenlenerek tekrar gönderilmesi gerekmektedir.
ErrorMap içeren örnek istek cevabı aşağıdaki gibidir:
{\n \"header\" : {\n \"requestId\" : \"f51af3e152b448fa84b84331f95ee783\",\n \"swtId\" : \"CC82C381E078482AB328943FCCB7100C\",\n \"returnCode\" : \"11\",\n \"reasonCode\" : \"1100\",\n \"message\" : \"İstek doğrulama hatası, detay için errorMap'e bakınız\",\n \"timestamp\" : 1616089736577,\n \"hashedData\" :\n\"4F1977ED2F17E2DD60BC283A1BAF0DF09ED759D0BB2589A150493AE8A2CF4243\n\" },\n \"errorMap\" : {\n \"additionalData\" : \"Gönderilebilecek en fazla karakter sayısı: 128\",\n \"card.expireMonth\" : \"Gönderilmesi gereken karakter sayısı: 2\",\n \"card.expireYear\" : \"Gönderilmesi gereken karakter sayısı: 2\"\n }\n}
Servis Cevaplardaki vposOrderId Alanı
- Akıllı Switch sistemi birden fazla banka ile entegredir ve bu bankaların orderid alanlarının data formatı birbirinden farklı olabilmektedir. Orderid alanı sebebiyle birincil işlemlerin hata almaması için Switch’in işlemi yönlendireceği sanalposa özel yeni bir orderid üretilebilir. Switch’in yeni bir orderid üretip üretmeme kararı iş yeri tarafından gönderilecek generateOrderId parametresi ile yönetilebilir.
- vposOrderId, istek mesajında generateOrderId “Y” veya boş olarak gönderildiyse ya da bu alan hiç gönderilmediyse Switch tarafından oluşturulan ve sanalposa iletilen orderId değeridir.
- generateOrderId alanı “N” gönderilirse Switch işlemin yönleneceği sanalposun formatına uygun yeni bir vposOrderId üretmeyecektir. İşlemde iş yerinin ilettiği orderid gidilecek sanalposa iletilecek olduğundan, orderid sanalposun beklediği formatta olmazsa sanalpos ilgili alan sebebiyle işlem isteğine hata verebilir.
- generateOrderId alanı “N” gönderilir ancak orderid değeri iletilmezse Switch bir orderid üretir ancak bu id gidilecek posun formatına göre yaratılmaz.
- generateOrderId alanının “Y” gönderildiği, boş gönderildiği veya bu alanın hiç gönderilmediği işlem isteklerinde orderId alanı dolu olursa bu değer response mesajında orderId alanında dönmeye devam eder. Ancak işlem banka ekranlarından vposOrderId değeri ile görüntülenmelidir. Switch ekranlarında her iki orderId değeri de gösterilecektir; bu ekranlarda vposOrderId değeri Banka Sipariş Numarası altında, İşlem Detay ekranında ise Banka Provizyon Detayı altındaki ORDER_ID alanında gösterilir. generateOrderId alanının “Y” gönderildiği, boş gönderildiği veya bu alanın hiç gönderilmediği işlem isteklerinde orderId alanı boş olursa Switch farklı bir orderId değeri ile farklı bir vposOrderId değeri oluşturur.
- generateOrderId alanının “Y” gönderildiği, boş gönderildiği veya bu alanın hiç gönderilmediği işlem isteklerinde orderId alanı boş olursa bir orderid bir de vposOrderID değeri üretilir.
- generateOrderId alanının “N” gönderildiği işlem isteklerinde işlemin orderId değeri ile vposOrderId değeri aynı olur.
- Sipariş sorgulama servisinde her zaman birincil işlem sonucunda dönen orderId alanında yer alan değer gönderilmelidir.
Kart Saklama ve Switch Dönüş Kodları ve Açıklamaları
Kart Saklama ve Switch sisteminden dönüşü sağlanacak return-reason kodlarıve açıklamaları aşağıdaki tabloda verilmiştir.
| Return Code (Dönüş Kodu) | Reason Code (Alt Dönüş Kodu) | Açıklama |
|---|---|---|
| 00 | 00 | İşlem başarı ile gerçekleşmiştir. |
| 01 | 01 | Acquirer, atılan işlemi onaylamadığ ıdurumlarda bu hata alınır. Örneğin satış isteğinin başarısız olduğu bir durumda veya 3D HTML isteğinde doğrulamanın başarısız olduğu durumda bu hata alınacaktır.Sipariş sorgulama servisi ise sorgucevabında başarısız işlemler için 01 hata kodunu header’da döner. |
| 01 | 02 | Sipariş sorgulama servisi, sorgu cevabında sanalposta bulunmayan işlemler için döner. Nestpay sanalposuna iletilememiş iptal işlemleri için Reason Code 02 değil, 01 dönecektir. |
| 02 | 04 | Sipariş sorgulama servisi, sorgu cevabında sanalposta bulunmayan 3D’li işlemler için döner. Bu cevap alındığında, 3D’li işlemin henüz tamamlanmamış olma ihtimalibulunduğundan yeniden sorgugönderilebilir. Reason Code 00 veya 01 olana dek sorgu gönderilebilir. Ancak kart sahibi işlemi yarıda bıraktıysa ve işlem sonuçlanmadıysa Reason Code her zaman 04 kalmaya devam edecektir. |
| 03 | 03 | İstek atılması istenen Sanalpos’aerişilememektedir |
| 10 | 1000 | Geçersiz http istek tipi. Sistem gelen http isteğini okuyamadığı durumda bu hata alınır. |
| 11 | 1100 | İstek doğrulama hatasıdır. Cevapta dönen errorMap’te hatanın detayı bulunur. Buradaki yönergelere göre düzenleme yapılması gerekmektedir. |
| 12 | 1200 | Yapılan işlemde bulunan orderId değeri ile işlem gerçekleştirilememiştir. Yeni birorderId ile istek atılmalıdır. |
| 12 | 1201 | İstekte atılan kur bilgisi ile siparişte bulunan kur bilgisi aynı değil. |
| 12 | 1202 | Geçerli sipariş bulunamadı hatası. Üzerinde işlem yapılmak istenen sipariş bilgisi sistemde mevcut değil. Örneğin satışı olmayan bir işlemin iptali veya iadesi gönderilirse bu hata alınır. |
| 13 | 1300 | Geçerli işlem bulunamadı hatası. Üzerinde işlem yapılmak istenen işlem bilgisi sistemde mevcut değil. Örneğin atılan istekte sipariş mevcut fakat işlem bulunamadıysa bu hatayı verecektir. |
| 13 | 1301 | Geçersiz işlem tipi. Yapılmaya çalışılan işleme izin verilmemektedir. Örneğin iadeisteği sadece satışı olan işlemlerdeuygulanabilir. Orjinali satıştan farklı bir işlem tipine iade isteği gönderilirse bu hata alınır. İptal isteği için de bu durum geçerlidir. |
| 13 | 1302 | Başarısız olan bir satış için iptal ya da iade isteği atılırsa bu hata alınır. |
| 31 | 3101 | Sanalpos cevabı Sw itch tarafındanişlenemedi. |
| 67 | 6700 | Şifreleme hatası. Genel olarak geçici bir hatadır. Yeniden birkaç işlem denemek gerekmektedir. Çok sık alınması durumunda ETicaretDestek@garantibbva.com.tr ile ietişime geçebilirsiniz. |
| 78 | 109 | Token almak için (full kart + skt) veya (ilk 6 - son 4 ve müşteri / kimlik numarası) gönderilmelidir. |
| 78 | 300 | Token isteği sırasında kart şifrelenirken hata ile karşılaşıldı. Tekrar işlem denenmelidir. |
| 78 | 401 | Token isteğinde atılan kartın durumu provizyon almaya müsait olmadığı için token üretilemedi. Kartın durumu kontrol edilmelidir. |
| 78 | 402 | Token isteğinde atılan kartın statüsü token alma işlemi için müsait değil. Kartın durumu kontrol edilmelidir. |
| 78 | 500 | Token isteği sırasında geçerli parametre tanımı bulunamadı. İstek içerisinde gönderilen sw tId için parametre tanımı yapılması gerekmektedir. Bunun için ETicaretDestek@garantibbva.com.tr ile iletişime geçilmelidir. |
| 78 | 500 | Token bulunamadı. Gönderilen token bilgisi kontrol edilmelidir. Silinmiş bir token ile işlemyapılmaya çalışılıyor olabilir. |
| 78 | 99 | Genel hata. Bazı durumlarda geçiciolabilmektedir. Çok sık alınması durumunda ETicaretDestek@garantibbva.com.tr ile iletişime geçilebilir. |
| 83 | 8300 | Datasal hata. Atılan istekteki datalar kontrol edilmelidir. Sorun tespit edilmezse E-Ticaret Destek ekibiyle iletişime geçilmelidir. |
| 99 | 99 | Sistem hatası. Bazı durumlarda geçici olabilmektedir. Çok sık alınması durumunda ETicaretDestek@garantibbva.com.tr ile iletişime geçilebilir. |
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.
