• 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.

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.

Ön Otorizasyon İsteklerinde Gönderilmesi Gereken Parametreler

Kart ile ön otorizasyon ve token ile ön otorizasyon işlemleri için istek yapılacak API adresleri farklı olmasına karşın istek-cevap mesaj yapısı her iki API için de aynıdır. İstek mesajlarındaki tek fark tokenlı isteklerde kart numarası yerine token bilgisinin gönderilmesidir.

Ön otorizasyon ve token ile ön otorizasyon servislerine Request Header tag’ına ek olarak gönderilmesi gereken parametreler aşağıdaki şekildedir:

Acquirer Banka Bilgisi

Alan Tip Zorunluluk Uzunluk Açıklama
bankId String Hayır - İşlem belirli bir bankanın Sanalpos’u üzerinden gönderilmek isteniyor ise bu alan kullanılır. Gönderilebilecek değer: Banka Kodu ve Adı: 64: İŞ BANK A.Ş. 62:T.GARANTİ BANKASI A.Ş 46: AKBANK T.A.Ş. 111: QNB  FİNANSBANK  A.Ş. 10: T.C. ZİRAAT BANKASI A.Ş. 12: T. HALK BANKASI A.Ş.

Kart Bilgileri

Alan Tip Zorunluluk Uzunluk Açıklama
cvv String Hayır 3 Karakter Kartın arkasında bulunan 3 haneli sayıdır.
expireMonth String Kart ile Satış API’ı kullanılıyor ise evet 2 Karakter Kartın üzerindeki ay.
expireYear String Kart ile Satış API’ı kullanılıy or ise evet 2 Karakter Kartın üzerindeki yıl.
first6 String Hayır 6 Karakter Kartın ilk 6 hanesi.
holderName String Hayır Max 50 Karakter Kartın üzerindeki isim.
last4 String Hayır 4 Karakter Kartın son 4 hanesi.
number String Kart ile Satış API’ı kullanılıyor ise evet Min : 15 KarakterMax : 30 Karakter Kartın numarası.
token String Saklanan Kart(Token) ile SatışAPI’ı kullanılıyor ise evet 32 Karakter Token Alma işlem sonucunda dönen kart ile ilişkili TokenID bilgisidir.

İşlem Bilgileri

Alan Tip Zorunluluk Uzunluk Açıklama
txnAmount String Evet - İşlem tutarı. Kuruş bilgisini nokta ile ayırmak gerekmektedir. Örnek : 1.45
currencyNumber String Evet 3 Karakter Döviz kuru bilgisi. 3 haneli ISO standart kodlar gönderilmelidir. Örnek : 949
installmentCount String Taksitli işlem gönderiliyor ise evet Max 3 Karakter Taksitli işlem gönderilecek ise taksit sayısı bu alanda gönderilmelidir. Örneğin; 3 taksitli işlem için '3' olarak gönderilmelidir.
motoInd String MOTO işlem gönderiliyor ise evet 1 Karakter Mail / Telefon order işlem gönderiliyor ise 'Y' olarak işaretlenmelidir.
orderId String Hayır Max 36 Karakter İşleme ait sipariş numarasıdır. Her işleme özel olarak belirlenmelidir.
orderGroupId String Hayır Max 36 Karakter İşleme ait sipariş grup numarasıdır.
generateOrderId String Hayır 1 Karakter İş yeri işlemde gönderdiği orderId’nin sanalposa iletilmesini istiyorsa “N”, Sw itch’in işlemin yönlendirileceği sanalposun orderId yapısına uygun yeni bir orderId üretmes i isteniyorsa “Y” gönderilmelidir. Alan hiç gönderilmezse veya değeri boş gönderilirse de Sw itch yeni bir orderId üretir.
additionalData String Hayır Max 120 Karakter Token ile birlikte satış isteğinde additionalData değeri gönderilirse, token’ın ilgili additionalData için kullanılıp kullanılamayacağı kontrolü yapılır ve provizyona devam edip etmeme kararı, değerin token alınan andaki değerle aynı olup olmadığına göre belirlenir.

Kart Sahibi Bilgileri

Alan Tip Zorunluluk Uzunluk Açıklama
customerNumber String Hayır Max 20 Karakter Garanti Bankası müşteri numarası.
email String evet Max 128 Karakter Müşteri e-posta adres bilgisidir.
gsm String Hayır Max 16 Karakter Müşteri cep telefonu numarası bilgisidir.
ip String Evet Max 20 Karakter Müşteri IP adres bilgisidir. Ipv4 formatında olmalıdır.
lastName String Hayır Max 50 Karakter Müşteri soyad bilgisidir.
name String Hayır Max 50 Karakter Müşteri ad bilgisidir.
nationalNumber String Hayır Max 20 Karakter Müşteri TCKN bilgisidir.

Fatura Adres Detay Bilgileri

Alan Tip Zorunluluk Uzunluk Açıklama
addressDetail String Hayır Max 256 Karakter Fatura adres detayı ( Semt , mahalle, cadde, kapı kodu vs).
city String Hayır Max 50 Karakter Fatura gönderilecek şehir bilgisi.
companyName String Hayır Max 64 Karakter Fatura gönderilecek şirket bilgisi.
country String Hayır Max 50 Karakter Fatura gönderilecek ülke bilgisi.
email String Evet Max 128 Karakter Faturanın gönderileceği kişiye ait e-posta adresi.
gsm String Hayır Max 16 Karakter Faturanın     gönderileceği     kişiye ait cep telefonu numarası.
lastName String Hayır Max 50 Karakter Faturanın gönderileceği kişinin soyadı.
name String Hayır Max 50 Karakter Faturanın gönderileceği kişinin adı.
phone String Hayır Max 36 Karakter Faturanın gönderieceği yer ile ilişkili telefon bilgisi.
zipCode String Hayır Max 16 Karakter Faturanın gönderileceği adresin posta kodu.

Kargo Adres Detay Bilgileri

Alan Tip Zorunluluk   Açıklama
addressDetail String Hayır Max 256 Karakter Kargo adres detayı ( Semt , mahalle, cadde, kapı kodu vs).
city String Hayır Max 50 Karakter Kargo gönderilecek şehir bilgisi.
companyName String Hayır Max 64 Karakter Kargo gönderilecek şirket bilgisi.
country String Hayır Max 50 Karakter Kargo gönderilecek ülke bilgisi.
email String Evet Max 128 Karakter Kargonun gönderileceği kişiye ait e-posta adresi.
gsm String Hayır Max 16 Karakter Kargonun     gönderileceği     kişiye ait cep telefonu numarası.
lastName String Hayır Max 50 Karakter Kargonun gönderileceği kişinin soyadı.
name String Hayır Max 50 Karakter Kargonun gönderileceği kişinin adı.
phone String Hayır Max 36 Karakter Kargonun gönderileceği yer ile ilişkili telefon bilgisi.
zipCode String Hayır Max 16 Karakter Kargonun gönderileceği adresin posta kodu.

Ön Otorizasyon (Preauth)

Ön otorizasyon (preauth) olarak gönderilen işlemlerde işlem tutarı ön otorizasyon kapama (postauth) gününe kadar bloke edilir, ilgili tutar kapama gününde provizyona yansıtılır. Ön otorizasyon işlemi yapıldığı an itibariyle kart sahibi ilgili işlemi hesap hareketlerinde görebilir.

Switch uygulamasında açık kart verisi ya da saklanan kart verisi (token) ile ön otorizasyon işlemleri API ile üye iş yerleri tarafından tetiklenebilir.

Saklanan Kart ile Ön Otorizasyon (Preauth)

Üye iş yerleri saklanan kart verisi ile yani token ile aşağıdaki API’lara istek yollayarak otorizasyon isteği gönderebilirler.

Ortam API Uzantıları

Test Ortamı Bağlantısı:\nhttps://gbtaksimtunel-integration.garanti.com.tr/api/payment/token/preauth\n\nÜretim Ortamı Bağlantısı:\nhttps://kartsaklamabackend.garanti.com.tr/api/payment/token/preauth\n

Json İstek Örneği

{\n \"header\": {\n \"requestId\": \"ornekrequest_tokenpreauth_1\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"userId\": \"PROVAUT\",\n \"hashedData\": \"E81AF7DBFB438F0B0907CD71C5FEB22039F62F854723917B4BF00AE71CFD89D5 \",\n \"timestamp\": \"31052019002\"\n },\n \"txnAmount\": 200,\n \"generateOrderId\": \"Y\",\n \"currencyNumber\": 949,\n \"installmentCount\": 0,\n \"orderId\": \"tokenpreauth_orderid\",\n \"orderGroupId\": \"swt_001\",\n \"card\": {\n \"holderName\": \"Card Holder\",\n \"token\": \"01C850F07F7C4DAC8B4F9508DAA10F9A\"\n },\n \"acquirer\": {\n \"bankId\": \"\"\n },\n \"cardHolder\": {\n \"name\": \"Name\",\n \"lastName\": \"Surname\",\n \"gsm\": \"5554443322\",\n \"email\": \"cem@cem.com.tr\",\n \"ip\": \"1.1.1.1\",\n \"nationalNumber\": \"18007904400\",\n \"customerNumber\": \"7449731\"\n },\n \"billingAddress\": {\n \"name\": \"Work Address\",\n \"lastName\": \"Work Address\",\n \"companyName\": \"Company Name\",\n \"city\": \"City\",\n \"country\": \"Country\",\n \"zipCode\": \"34212\",\n \"addressDetail\": \"Work Adress\",\n \"phone\": \"5354190000\",\n \"gsm\": \"5354190000\",\n \"email\": \"your@mail.com\"\n },\n \"shippingAddress\": {\n \"name\": \"Shipping Adress\",\n \"lastName\": \"Shipping Address\",\n \"companyName\": \"Shipping Company\",\n \"city\": \"City\",\n \"country\": \"Conutry\",\n \"zipCode\": \"34212\",\n \"addressDetail\": \"Work Adress\",\n \"phone\": \"5354190000\",\n \"gsm\": \"5354190000\",\n \"email\": \"your@mail.com\"\n },\n \"additionalData\": \"\"\n}

Json İstek Cevabı Örneği

{\n \"header\": {\n \"requestId\": \"ornekrequest_tokenpreauth_1\",\n \"swtId\": \"CC82C381E078482AB328943FCCB7100C\",\n \"returnCode\": \"00\",\n \"reasonCode\": \"00\",\n \"message\": \"Başarılı\",\n \"timestamp\": \"2021-09-03T08:34:14.036+0000\",\n \"hashedData\": \"76892B6C17F2A647B2EEF918665404E2274E84FABC94CBC0FF3A5A0D22FB2872\"\n },\n \"orderId\": \"tokenpreauth_orderid\",\n \"orderGroupId\": \"swt_001\",\n \"txnAmount\": 200,\n \"installmentCount\": 0,\n \"card\": {\n \"token\": \"01C850F07F7C4DAC8B4F9508DAA10F9A\",\n \"binNumber\": \"450803\",\n \"maskedNumber\": \"450803******4509\"\n },\n \"acquirerId\": \"64\",\n \"acquirerResponse\": {\n \"terminalId\": \"\",\n \"merchantId\": \"\",\n \"orderId\": \"ORDR83C6B08A669E4B118FF390E47FA8B235\",\n \"orderGroupId\": \"swt_001\",\n \"returnCode\": \"00\",\n \"reasonCode\": \"00\",\n \"errorMessage\": \"\",\n \"retRefNum\": \"21246LiPF10019\",\n \"authCode\": \"P72742\",\n \"provisionDate\": \"20210903 11:34:15\",\n \"extraData\": {\n \"orderId\": \"ORDR83C6B08A669E4B118FF390E47FA8B235\",\n \"groupId\": \"swt_001\",\n \"response\": \"Approved\",\n \"authCode\": \"P72742\",\n \"hostRefNum\": \"124600050752\",\n \"procReturnCode\": \"00\",\n \"transId\": \"21246LiPF10019\",\n \"errMsg\": \"\",\n \"extra.settleid\": \"2024\",\n \"extra.trxdate\": \"20210903 11:34:15\",\n \"extra.errorcode\": \"\",\n \"extra.hostdate\": \"0903-113415\",\n \"extra.numcode\": \"00\"\n },\n \"orderInquiryResult\": {\n \"statusCode\": \"01\",\n \"authAmount\": 0,\n \"txnReasonCode\": \"00\"\n }\n },\n \"vposOrderId\": \"ORDR83C6B08A669E4B118FF390E47FA8B235\"\n}

Ön Otorizasyon İşlemleri Cevabı

Kart ile ön otorizasyon ve token ile ön otorizasyon işlemleri için Response Header alanına ek olarak servisten aşağıdaki alanlar dönülecektir:

Alan Tip Açıklama
orderId String İstek mesajında gönderilen sipariş bilgisi.
orderGroupId String İstek mesajında gönderilen siparişin grup bilgisi.
vposOrderId String İstek mesajında generateOrderId Y veya boş olarak gönderildiyse ya da bu alan hiç gönderilmediyse Sw itch tarafından oluşturulan orderid değeridir.
txnAmount String İşlem tutarı.
installmentCount String İşlemde gönderilen taksit sayısı.
acquirerId String İşlemin gönderildiği pos banka ID'si.

Kart Bilgileri

Alan Tip Açıklama
binNumber String Kart numarasının ilk 6 hanesidir.
maskedNumber String Maskeli kart numarası bilgisidir.
bankName String Kartın ait olduğu banka.
token String Token ile gönderilen bir istek ise Token ID bilgis i bu alanda döner.

Acquirer Cevabı (Sanalpos Tarafından Dönen Cevap)

Alan Tip Açıklama
terminalId String İşlemin geçtiği Sanalpos terminal bilgisidir.
merchantId String İşlemin geçtiği Merchant numarası bilgisidir.
orderId String İşleme ait sipariş numarası bilgisidir.
orderGroupId String İşleme ait sipariş grup numarası bilgisidir.
returnCode String İşlem sonuç kodudur.
reasonCode String İşlem sebep kodudur.
errorMessage String İşlemde hata mevcutsa, ne olduğu bu alanda iletilecektir.
retRefNum String İşleme ait retref numarasıdır.
authCode String Sanalpos tarafından dönen auth kodu bilgisidir.
provisionDate String İşlemin geçtiği provizyon tarihidir.
extraData Map<String, Object> Sanalpos tarafından ek olarak iletilen datadır.

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.

Sizden haber almak isteriz. Hizmetlerle ilgili sorunlarınız/sorunuz mu var? Bize bununla ilgili ayrıntılı bir e-posta gönderir misiniz?

Bize Soru Gönderin Bize Soru Gönderin