Üye iş yerleri saklanan kart verisi ya da açık kart verisi ile Switch 3D Gateway’e HTML POST metodu ile istek göndermek sureti ile birden fazla banka Sanal PoS’una satış, taksitli satış ve ön otorizasyon ve taksitli ön otorizasyon işlemleri için 3D ödeme isteği gönderebilir.
Üye iş yerlerinden üretim ortamında oluşturulan 3D istek formunu Switch 3D Gateway’e post etmeden önce, Switch Yönetim Ekranları’ında yer alan Banka Tanımlama menüsü altında hali hazırda kullandıkları bankalar için PoS credential bilgilerini girmeleri beklenmektedir. Bu adımdan sonra Switch sistemi ilgili Üye İşyerinin her banka için tanımladığı değerleri şifreli olarak saklar.
Akıllı Switch sistemi, üye işyerinin 3D istek tetiklemek sureti ile başlattığı işlemlerde hangi bankaya ödeme isteği gönderileceğine karar verir, sistemde şifreli olarak sakladığı banka credential bilgileri ile 3D Ödeme formunu hazırlar ve ilgili Acquirer bankaya isteği iletir.
Acquirer banka tarafından alınan 3D istek, 3D işlem formuna dönüştürülerek diğer modüller aracılığı ile kart bankasına iletilir ve kart sahibine doğrulama işlemi yapacağı ekran gösterilir.
Kart sahibi 3D doğrulama işlemini tamamlamasının ardından Switch 3D Gateway, üye işyerinin HTML POST içerisinde belirttiği success ya da fail URL üzerinden 3D işlem sonucunu işyerine döner.
Akıllı Switch sistemi ile;
➢ Üye işyeri tarafından API içerisinde gönderilen banka ID’sine istinaden direkt olarak ilgili bankaya ödeme isteği gönderilebilir
➢ Üye işyeri api içerisinde banka ID göndermez ise işlem yapılan kartın bankasına ödeme isteği gönderilebilir
➢ Üye işyeri API içerisinde banka ID göndermez ve işlem yapılan kartın bankası Switch sisteminde entegre bir banka değil ise üye işyerinin default olarak tanımladığı banka üzerinden ödeme isteği gönderilebilir
➢ Default banka tanımlanmamış ise tanımlı bankalardan herhangi birine istek gönderilebilir.
Üye işyeri tarafından hazırlanacak HTML formunda POST isteğinin gönderileceği adresler ve forma alanları aşağıdaki gibidir. Alanların her biri String olarak gönderilebilir.
Alan | Zorunluluk | Uzunluk | Açıklama |
---|---|---|---|
swtId | Evet | Max 36 Karakter | İşlem gerçekleştiren işyeri ya da firma adına tanımlanmış Switch ID değerinin gönderildiği alandır. |
requestId | Evet | Max 36 Karakter | Her işlem için üretilen unique ID değeridir. |
level | Evet | - | 3D secure sonrasında işlemin provizyon devam edip etmeyeceğinin belirlendiği modelbilgisidir. Bu alan 3D_PAY olarak set edilecektir. |
cardNumber | cardToken alanı boş ise evet | Min:15 KarakterMax:30 Karakter | Kart numarası. |
cardExpireYear | cardToken alanı boş ise evet | 2 Karakter | İşlemde kullanılan kartın son kullanma tarihinin yıl bilgisinin gönderildiği alandır. |
cardExpireMonth | cardToken alanı boş ise evet | 2 Karakter | İşlemde kullanılan kartın son kullanma taihinin ay bilgisinin gönderildiği alandır. |
cardCvv | Hayır | 3 Karakter | İşlemde kullanılan kartın CVV bilgisinin gönderildiği alandır. |
cardToken | Saklanan kart ile yapılan otorizasyon işlemleri için evet | Max 32 Karakter | Token ID bilgisinin gönderildiği alandır. |
orderId | Hayır | Max 36 Karakter | Sipariş numarasının gönderildiği alandır. |
generateOrderId | Hayır | 1 Karakter | İş yeri işlemde gönderdiği orderId’nin kullanılmasını istiyorsa alanın değeri “N”, Switch’in işlemin yönlendirileceği sanal posun orderId yapısına uygun yeni bir orderId üretmesi isteniyorsa “Y”gönderilmelidir.Alan hiçgönderilmezse veya değeriboşgönderilirse de Switch yeni bir orderId üretir. |
userId | Evet | Max 36 Karakter | İşlem gerçekleştiren kullanıcının ID değerinin gönderildiği alandır. |
txnType | Evet | - | İşlem bilgisinin yollandığı alandır. Satış işlemleri için "sales", ön otorizasyon işlemleri için “preauth” olarakgönderilmelidir. |
txnAmount | Evet | - | İşlem tutarının yollanacağı alandır. Kuruş ayrımı “.” ile sağlanacaktır. Örnek : 1.45 |
txnCurrencyCode | Evet | 3 Karakter | Kur bilgisinin yollandığı alandır. ISO standartlarında 3 haneli kod gönderilecektir.Örnek : 949 |
txnInstallmentCount | Hayır | Max 3 Karakter | İşlem taksit sayısının yollanacağı alandır. |
companyName | Hayır | Max 64 Karakter | Sayfa gösterimlerinde kullanılacak işyeri isim bilgisi yer alacaktır. |
successUrl | Evet | - | Başarılı işlem cevabının döndürüleceği işyerine ait adres bu alanda yer alacaktır. |
failureUrl | Evet | - | Hatalı işlem cevabının döndürüleceği işyerine ait adres bu alanda yer alacaktır. |
txnMotoInd | Hayır | 1 Karakter | Yapılan işlemin mail order bir işlem olup olmadığı bilgisinin yollandığı alandır. 'Y' ise mail order işlem olarak algılanacaktır. |
txnTimestamp | Evet | - | İşlem zamanı bu alanda gönderilir. |
lang | Evet | - | Dil bilgisinin gönderildiği alandır. "tr" değeriningönderilmesi beklenir. |
refreshTime | Evet | - | Banka tarafında bir sayfa gösterimi olduğunda kullanılan alandır. 5 değeri gönderilmelidir. |
customerName | Hayır | Max 50 Karakter | Kart sahibinin isim bilgisi yer alacaktır. |
customerLastName | Hayır | Max 50 Karakter | Kart sahibinin soy isim bilgisi yer alacaktır. |
customerGsm | Hayır | Max 16 Karakter | Kart sahibinin GSM bilgisi yer alacaktır. |
customerIp | Evet | Max 20 Karakter | Kart sahibinin IP bilgisi yer alacaktır. Ipv4 formatında olmalıdır. |
customerEmail | Evet | Max 128 Karakter | Kart sahibinin email bilgisi yer alacaktır. |
customerNationalNumber | Hayır | Max 20 Karakter | Kart sahibinin TCKN bilgisi yer alacaktır. |
acqId | Evet | - | İşlem belirli bir bankanın sanalposu üzerindengönderilmek isteniyor isebu alan kullanılır. İstenilen Sanalpos için aşağıdaki rakamlara tekabül eden Id’ler kullanılmalıdır.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.Ş.67: YAPI KREDİ BANKASI |
hashedData | Evet | - | 3D ile Ödeme Request Hash Hesaplama başlığı altındaanlatılankritelere uygun olarak işyeri tarafından oluşturularak istekiçerisindegönderilecektir. |
shippingAddress.name | Hayır | Max 50 Karakter | Kargo adresine ait kişinin isim bilgisi yer alacaktır. |
shippingAddress.lastName | Hayır | Max 50 Karakter | Kargo adresine ait kişinin soyisim bilgisi yer alacaktır. |
shippingAddress.companyName | Hayır | Max 64 Karakter | Kargo adresine ait sirket adı bilgisi yer alacaktır. |
shippingAddress.city | Hayır | Max 50 Karakter | Kargo adresine ait şehir adı bilgisi yer alacaktır. |
shippingAddress.country | Hayır | Max 50 Karakter | Kargo adresine ait ülke adı bilgisi yer alacaktır. |
shippingAddress.zipCode | Hayır | Max 16 Karakter | Kargo adresine ait posta kodu bilgisi yer alacaktır. |
shippingAddress.addressDetail | Hayır | Max 256 Karakter | Kargo adresine ait detay adres alanı bilgisi yer alacaktır. |
shippingAddress.phone | Hayır | Max 36 Karakter | Kargo adresine ait telefon bilgisi yer alacaktır. |
shippingAddress.gsm | Hayır | Max 16 Karakter | Kargo adresine ait GSM bilgisi yer alacaktır. |
shippingAddress.email | Hayır | Max 128 Karakter | Kargo adresine ait mail bilgisi yer alacaktır. |
billingAddress.name | Hayır | Max 50 Karakter | Fatura adresine ait kişinin isim bilgisi yer alacaktır. |
billingAddress.lastName | Hayır | Max 50 Karakter | Fatura adresine ait kişinin soyisim bilgisi yer alacaktır. |
billingAddress.companyName | Hayır | Max 64 Karakter | Fatura adresine ait sirket adı bilgisi yer alacaktır. |
billingAddress.city | Hayır | Max 50 Karakter | Kargo adresine ait şehir adı bilgisi yer alacaktır. |
billingAddress.country | Hayır | Max 50 Karakter | Kargo adresine ait ülke adı bilgisi yer alacaktır. |
billingAddress.zipCode | Hayır | Max 16 Karakter | Kargo adresine ait posta kodu bilgisi yer alacaktır. |
billingAddress.addressDetail | Hayır | Max 256 Karakter | Kargo adresine ait detay adres alanı bilgisi yer alacaktır. |
billingAddress.phone | Hayır | Max 36 Karakter | Kargo adresine ait telefon bilgisi yer alacaktır. |
billingAddress.gsm | Hayır | Max 16 Karakter | Kargo adresine ait GSM bilgisi yer alacaktır. |
billingAddress.email | Hayır | Max 128 Karakter | Kargo adresine ait mail bilgisi yer alacaktır. |
hashVersion | Evet | - | “2.0” olarakgönderilmelidir. |
comments[0] comments[1] comments[2] comments[3] | Hayır | Max 20 Karakter | Garanti BBVAsanalposuna iletilencomment alanlarıdır. Bu alanda gönderilen data Switch tablolarında tutulmaz ve Garanti BBVA sanalposudışında bir sanalposailetilmez.Her bir comment alanı için maksimum uzunluk 20 karakterdir. |
3D secure response mesajı, üye işyerinin istek mesajında gönderdiği successUrl ya da failureUrl adreslerine aşağıda yer alan data seti ile birlikte Switch 3D Secure Gateway tarafından Html Form olarak POST edilecektir.
Alan | Açıklama |
---|---|
swtId | SwitchID bilgisinin dönüldüğü alandır. |
requestId | İstek sırasında işyeri tarafından gönderilen tekil ID bilgisinin dönüldüğü alandır. |
txnId | işlem ID bilgisinin dönüldüğü alandır. |
orderId | Sipariş numarasının dönüldüğü alandır. |
returnCode | Switch Cevap koduna ait bilgilerin dönüldüğü bir alandır. |
reasonCode | Switch Alt Cevap koduna ait bilgilerin dönüldüğü bir alandır. |
message | Cevap açıklamasının döndürüldüğü alandır. |
txnAmount | İşlem tutarının döndürüldüğü alandır. |
installmentCount | Taksit sayısının döndürüldüğü alandır. |
maskedNumber | Maskeli kart numarasının dönüleceği alandır. |
acquirerId | Provizyon alınan banka ID bilgisinin dönüldüğü alandır. |
acquirerName | Provizyon alınan banka isminin dönüldüğü alandır. |
hashedData | Cevap hash bilgisinin dönüldüğü alandır. Üye işyerinin bu alanda dönen hash değerini hesaplayarak doğrulaması beklenir. 3D ile Ödeme Response Hash Hesaplama başlığı altında anlatılan kritelere uygun olarak işyeri tarafından hesaplanması gerekmektedir. |
terminalId | işlem yapılan terminal bilgisinin dönüldüğü alandır. |
merchantId | İşlem yapılan işyeri numarasının dönüldüğü alandır. |
authCode | Onay alan provizyon işlemlerinde onay kodunun döndüğü alandır. |
successUrl | İşyerine ait başarılı işlem URL’inin dönüldüğü alandır. |
failureUrl | İşyerine ait başarısız işlem URL’inin dönüldüğü alandır. |
approved | İşlemin onaylanıp onaylanmadığı bilgisinin dönüldüğü alandır. |
retrefNum | Banka tarafındaki tekil işlem numarasının dönüldüğü alandır. |
eci | 3D secure doğrulaması sonucunda alınan ECI değerinin dönüldüğü alandır. |
cavv | 3D secure doğrulaması sonucunda alınan CAVV değerinin dönüldüğü alandır. |
md | 3D secure doğrulaması sonucunda alınan MD değerinin dönüldüğü alandır. |
xid | 3D secure doğrulaması sonucunda alınan XID değerinin dönüldüğü alandır. |
response | Switch uygulamasına ait sonuç bilgisinin dönüldüğü alandır. |
mdStatus | 3D secure doğrulaması sonucunda alınan MD STATUS değerinin dönüldüğü alandır. |
timestamp | Cevap mesajına ait timestamp bilgisinin dönüldüğü alandır. |
acqReturnCode | İşyeri bankası tarafında üretilen cevap kodunun döndürüldüğü alandır. |
acqReasonCode | İşyeri bankası tarafında üretilen alt cevap kodunun döndürüldüğü alandır. |
currencyCode | Kur kodunun döndürüldüğü alandır. |
extraData | Ek detay bilgilerinin dönüldüğü alandır. Bu alanda data olması halinde Map<String, String> dönüş sağlanacaktır. |
userId | İşlemi yapan kullanıcının dönüldüğü alandır. |
vposOrderId | İstek mesajında generateOrderId Y veya boş olarak gönderildiyse ya da bu alan hiç gönderilmediyse Switch tarafından oluşturulan orderid değeridir. |
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 :
3D ile ödeme alındıktan sonra merchanta gönderilen cevap formunda da hashedData isimli alan yer alacaktır. Merchant, 3D cevap formundadö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 :
3D ile ödeme için örnek HTML formu HTML Table formatında aşağıda verilmiştir. Buradaki alanlar istenilen şekilde doldurulup, 3D request hash hesabı yapılıp hashedData alanına set edildikten sonra aşağıda verilen test veya prod url’ine Form Submit edilerek 3D ile ödeme isteği tetiklenebilir. Post edilen data application/x-www-form-urlencoded tipinde olmalıdır.