Sanal Pos Entegrasyon Dokümanı 3D Secure Model Kuveyt Türk Katılım Bankası 2024 İçindekiler Tablosu Kuveyt Türk Sanal Pos (Freepos) Hakkında ................................................................................................... 2 1. Güvenli Ödeme Nedir? .............................................................................................................................. 2 2. Güvenli Ödeme Nasıl Çalışır?..................................................................................................................... 2 3. Güncellemeler ........................................................................................................................................... 3 3.1. 3D Secure 2.0 Geçişi .................................................................................................................. 3 3.1.1. Satış İşlemi Mesaj Örneği – Kart Doğrulanması (Request 1) ............................................. 3 3.1.2. Satış İşlemi Onay Mesaj Örneği – Ödeme Alınması (Request 2) ....................................... 4 3.2. URL Güncellemesi ...................................................................................................................... 5 3.3. iFrame Yapısının Engellenmesi .................................................................................................. 5 4. İşlemde Kullanılan Zorunlu Parametreler Ve Açıklamaları .................................................................... 5 4.1. Banka Tarafından Sağlanacak Bilgiler ................................................................................................. 7 4.2. Entegrasyon İçin Kullanılan Diğer Bilgiler ........................................................................................... 7 4.3. Banka Tarafında Dönen Cevap Bilgileri .............................................................................................. 9 5. Entegrasyon ............................................................................................................................................. 10 5.1. Kullanılan Mesaj Yapıları .................................................................................................................. 11 5.1.1. Satış İşlemi Mesaj Örneği – Kart Doğrulaması (Request 1) ....................................................... 11 5.1.2.Satış İşlemi Mesaj Örneği Banka Cevabı (Response 1) ............................................................... 12 5.1.3. Satış İşlemi Onay Mesaj Örneği – Ödeme Alınması (Request 2) ............................................... 13 5.1.4.Ödeme İşlem Sonucu Mesaj Yapısı (Response 2) ....................................................................... 13 5.2. Tarım İşyeri ....................................................................................................................................... 14 5.2.1. Satış İşlemi Mesaj Örneği – Kart Doğrulaması (Request 1) – Tarım İşyeri................................. 14 5.2.2.Satış İşlemi Mesaj Örneği Banka Cevabı (Response 1) - Tarım İşyeri ......................................... 15 5.2.3. Satış İşlemi Onay Mesaj Örneği – Ödeme Alınması (Request 2) - Tarım İşyeri ......................... 16 5.2.4.Ödeme İşlem Sonucu Mesaj Yapısı (Response 2) - Tarım İşyeri ................................................. 17 6. HashData Hesaplamaları ......................................................................................................................... 18 7. Örnek Kod Parçaları (PHP) ..................................................................... Hata! Yer işareti tanımlanmamış. 7.1. Ödeme İşlemi Yapılması (Kart Doğrulaması) .................................. Hata! Yer işareti tanımlanmamış. 7.2. İşlem Sonucunun Alınması ............................................................. Hata! Yer işareti tanımlanmamış. 7.3. Ödeme İşleminin Onaylanması....................................................... Hata! Yer işareti tanımlanmamış. 8. Sanal Pos Güvenli Ödeme Noktası Adresleri (Güncel)............................................................................. 19 9. Test Ortam Bilgileri .................................................................................................................................. 19 Kuveyt Türk Katılım Bankası 2024 Sayfa 1 Kuveyt Türk Sanal Pos (Freepos) Hakkında E-ticaret sitelerinde yapılan alışverişlerin gerçekleşmesinde kullanılan POS sistemidir. VPOS (Virtual POS) olarak da isimlendirilen bu sistem kredi kartı vasıtasıyla internet üzerinden alışveriş yapma imkânı sağlar. Siteniz vasıtasıyla alışveriş yapan müşteriniz; kredi kartı bilgilerinin sitedeki ödeme ekranlarına girer, bu bilgiler ilgili bankaya ulaşır ve işlemin provizyonu (Onay) alınır. Provizyonu alınmış işlemlerin tutarı ilgili müşterinin kredi kartı limitinden düşerek çalıştığınız banka hesabına geçirilir. Web site üzerinden çalışan on-line bir POS’tur. 1. Güvenli Ödeme Nedir? TROY, VISA ve MasterCard’ın dahil olduğu internet üzerinden gerçekleştirilen ödeme işlemlerinde daha güvenilir bir ortam sağlayan sistemdir. 3D Secure ve GO sistemleri kullanıcı, üye işyeri ve banka arasındaki sorumlulukları da düzenlemektedir. 3D Secure sistemi uygulanan ödeme işlemlerinde kullanıcıdan kart bilgileri alındıktan sonra, kullanıcı bankanın 3D Secure veya GO ödeme sayfasına yönlendirilmektedir. Burada kullanıcı banka tarafından kendisine gönderilen kısa mesajda yer alan şifreyi girer, böylece kart doğrulanmış ve yapılan işlem kullanıcı tarafından imzalanmış olmaktadır. Kuveyt Türk Katılım Bankası tarafından sunulan Sanal Pos servisi 3D Secure ve GO ödeme işlemlerini desteklemektedir. 2. Güvenli Ödeme Nasıl Çalışır? Üye işyerlerinin 3D Secure sistemini uygulayabilecekleri birçok yöntem bulunmaktadır. 3D Model bu yöntemlerden birisidir. Bu yöntem 3D Secure sisteminin faydaların tümünü sağlamaktadır. Bu yöntem ayrıca; üye işyerine kart doğrulama, kart doğrulaması sonrasında işlemi tekrar kontrol edebilme ve uygun olması durumunda provizyon işlemine onay verebilme imkanı sağlamaktadır. 3D Model uygulanmış tipik bir ödeme işlemi aşağıdaki temel adımlarla gerçekleşmektedir. • Kullanıcının karta ait bilgileri girmesi, • Kart sahibi banka tarafından kartın doğrulanması (kullanıcının gelen sms şifre ile işlemi onaylaması), • Doğrulama sonucunun üye işyeri tarafından kontrol edilmesi, • Ödemenin gerçekleştirilmesi. Bu adımların uygulanmasına dair teknik bilgiler daha sonraki bölümlerde yer almaktadır. Kuveyt Türk Katılım Bankası 2024 Sayfa 2 3. Güncellemeler 3.1. 3D Secure 2.X Sonrası Güncellemeler 3D Secure doğrulama altyapısı değiştiği için ödeme şemaları kuralları gereği, işyerlerinin 3D Secure 2.X geçişi ile birlikte işlem isteklerindeki yeni alanların göndermesi beklenmektedir. İşlem isteklerinde gönderilmesi gereken yeni bilgilerin listesi aşağıda verilmiştir. Bu bilgilere ait detaylı açıklamalar 4. İşlemlerde Kullanılan Zorunlu Parametreler ve Açıklamaları başlığında yer almaktadır. ▪ ▪ ▪ ▪ ▪ ▪ ▪ ▪ ▪ ▪ ▪ CardHolderName DeviceChannel ClientIP BillAddrCity BillAddrCountry BillAddrLine1 BillAddrPostCode BillAddrState Email Cc Subscriber 3.1.1. Satış İşlemi Mesaj Örneği – Kart Doğrulanması (Request 1) Post URL: https://sanalpos.kuveytturk.com.tr/ServiceGateWay/Home/ThreeDModelPayGate TDV2.0.0 http://localhost/php//ThreeDModetest/Approval.php http://localhost/php//ThreeDModetest/Fail.php TJcp1k5UUT/TSa5X2m0+82E9I/o= 496 400235 02 12.22.156.43 İstanbul 792 XXX Mahallesi XXX Caddesi No 55 Daire 1 34000 40 Kuveyt Türk Katılım Bankası 2024 Sayfa 3 xxxxx@gmail.com 90 1234567899 apitest **************** ** ** *** Test Troy Sale 0 500 500 0949 20201221 3 3.1.2. Satış İşlemi Onay Mesaj Örneği – Ödeme Alınması (Request 2) Post URL: https://sanalpos.kuveytturk.com.tr/ServiceGateWay/Home/ThreeDModelProvisionGate TDV2.0.0 ANcybxW/c1G39+RMstZ3ROYakO8= 496 400235 apitest Sale 0 100 20201221 3 MD BUdzLdTOnnrFP1/q1C/EgfrVxHvdvDtx2MuEusn+lB9My5kmogvb4JreoUYD1++6 Kuveyt Türk Katılım Bankası 2024 Sayfa 4 3.2. URL Güncellemesi 3D Secure ödeme akışında ödemeler, kart doğrulama ve ödeme alma olarak iki adımda tamamlanmaktadır. Mevcut adreslerin kullanımı 2024 yılı içerisinde kapatılacaktır. Mevcut Adresler 1. Sanal Pos Güvenli Ödeme Noktası – Kart Doğrulanması (Production) https://boa.kuveytturk.com.tr/sanalposservice/Home/ThreeDModelPayGate 2. Sanal Pos Güvenli Ödeme Onaylama – Ödeme Alınması (Production) https://boa.kuveytturk.com.tr/sanalposservice/Home/ThreeDModelProvisionGate Yeni Adresler 1. Sanal Pos Güvenli Ödeme Noktası – Kart Doğrulanması (Production): https://sanalpos.kuveytturk.com.tr/ServiceGateWay/Home/ThreeDModelPayGate 2. Sanal Pos Güvenli Ödeme Onaylama - Ödeme Alınması (Production): https://sanalpos.kuveytturk.com.tr/ServiceGateWay/Home/ThreeDModelProvisionGate 3.3. iFrame Yapısının Engellenmesi Yeni url adreslerimizin kullanımı ile birlikte kart doğrulamasında iframe yapısı güvenlik gerekçesi ile 31.12.2022 tarihinde sonlandırılmıştır. Iframe kullanılması durumunda hata alınacaktır. 4. İşlemde Kullanılan Zorunlu Parametreler Ve Açıklamaları Bu bölümde üye işyeri ve Sanal Pos servisi arasında gerçekleştirilecek entegrasyon için bilgiler yer almaktadır. Üye işyerinin 3D Model ödeme uygulayabilmesi için aşağıdaki bilgilere sahip olması gerekmektedir. Z: Zorunlu, O: Opsiyonel, K: Kullanılmıyor Alan Adı KuveytTurkVPosMessage(Başlangıç Tag) APIVersion OkUrl FailUrl HashData MerchantId UserId UserName O Z Z Z Z Z Z Kuveyt Türk Katılım Bankası 2024 Tip Text Text Tamsayı Tamsayı Text Sayfa 5 CardNumber CardExpireDateYear CardExpireDateMonth CardCVV2 CardHolderName CardType BatchID TransactionType InstallmentCount DeferringCount InstallmentMaturityCommisionFlag Amount DisplayAmount FECAmount CurrencyCode MerchantOrderId QryId DebtId SurchargeAmount SGKDebtAmount TransactionSecurity TransactionSide PaymentId OrderPOSTransactionId TranDate EntryGateMethod DeviceChannel ClientIP BillAddrCity BillAddrCountry BillAddrLine1 BillAddrPostCode BillAddrState Email Cc Subscriber Z Z Z Z Z O O Z Z O O Z Z O Z O K K K K Z O O O O O Z Z Z Z Z Z Z Z Z Z Kuveyt Türk Katılım Bankası 2024 Text Text Text Text Text Text Tamsayı Text Tamsayı Tamsayı Tamsayı Tamsayı Tamsayı Tamsayı Text Text Tamsayı Tamsayı Tamsayı Tamsayı Tamsayı Text Tamsayı Tamsayı Tarih Text Text Text Text Text Text Text Text Text Text Text Sayfa 6 4.1. Banka Tarafından Sağlanacak Bilgiler UserId (Müşteri Numarası): Üye işyerinin Kuveyt Türk'teki Sanal Pos’un bağlı hesaba ait müşteri numarasıdır. MerchantId (Mağaza Numarası): Üye işyerinin Kuveyt Türk Sanal Pos servisinde kayıtlı özel mağaza numarasıdır. Başvuru onay mailinde üye işyerine gönderilmektedir. PostURL (Ödeme Noktası Adresi): Sanal Pos'un sunduğu ödeme yöntemine ait adreslerdir. Ödeme işlemine ait bilgiler bu adrese gönderilecektir. • Sanal Pos Güvenli Ödeme Noktası (Kart Doğrulaması): https://sanalpos.kuveytturk.com.tr/ServiceGateWay/Home/ThreeDModelPayGate • Sanal Pos Güvenli Ödeme Onaylama (Ödeme Alınması): https://sanalpos.kuveytturk.com.tr/ServiceGateWay/Home/ThreeDModelProvisionGate 4.2. Entegrasyon İçin Kullanılan Diğer Bilgiler APIVersion (Uygulama Versiyonu): Uygulama versiyonunu ifade etmektedir. Eylül 2022’den itibaren 3D Secure 2.0 geçişi ile TDV2.0.0 gönderilmelidir. OkUrl (Başarılı İşlem Adresi): Güvenli Ödeme işlemlerinde kartın doğrulanması aşamasında, kullanıcı bir başka sayfaya yönlendirilmektedir (ACS veya TroyGo). Bu aşamada işlemler arasında bağlantı bulunmamaktadır. Bu nedenle işlemlere ait sonuçlar üye işyerinin belirleyeceği bir sayfaya gönderilmektedir. 3D Secure ve GO ile kart doğrulaması başarılı gerçekleştiğinde “Kart Doğrulandı.” sonucunun gönderileceği adrestir. (& içeremez. & şeklinde tanımlanmalıdır.) FailUrl (Başarısız İşlem Adresi): Kart doğrulaması başarısız olan işlemlerde veya parametrelere bağlı olarak alınabilecek hatalarda sonucun gönderileceği adrestir. Üye işyerinin belirleyeceği bir sayfaya gönderilmektedir. (& içeremez. & şeklinde tanımlanmalıdır.) HashData (Doğrulama Anahtarı): Ödeme işlemine ait bilgilerin doğruluğunun kontrol edilmesi için kullanılan veridir. Daha sonra sağlanacak algoritma ile üretilecek bu veri, Sanal Pos tarafında da üretilerek bu veriler karşılaştırılmaktadır. Bu kontrolden geçemeyen ödemeler gerçekleştirilmemektedir. CardNumber (Kart Numarası): Ödemeyi yapacak kişiye ait kartın üzerindeki 16 haneli numaradır, 16 karakter olacak ve aralarında boşluk/sembol olmayacak şekilde gönderilmelidir. CardExpireDateYear (Kart Son Kullanım Yılı): Kartın ön yüzünde bulunan son kullanma tarihine ait yıl bilgisi, 2 karakter olarak gönderilmelidir. (Örneğin; 2025 için 25) CardExpireDateMonth (Kart Son Kullanım Ayı): Kartın ön yüzünde bulunan son kullanma tarihine ait ay bilgisi, 2 karakter olarak gönderilmelidir. (Örneğin; Ocak ayı için 01) CardCVV2: Kartın arka yüzündeki 3 haneli güvenlik kodudur. 3 karakter olarak gönderilmelidir. Kuveyt Türk Katılım Bankası 2024 Sayfa 7 CardHolderName (Kart Sahibinin Adı Soyadı) : Kartın ön yüzünde yer alan adı ve soyadı bilgisi gönderilmelidir. CardType (Kart Türü) : TROY, VISA veya MasterCard olarak gönderilmelidir. Default bir değer kullanılabilir. (Örneğin; VISA) BatchID (Günsonu Numarası): Satış işleminde sabit değer 0 gönderilmelidir. TransactionType (İşlem Türü) : Sabit değer olarak “Sale” gönderilmelidir. InstallmentCount (Taksit Sayısı): Taksit sayısı bu alana girilmelidir, taksit yapma yetkiniz bulunmuyorsa 0 olarak gönderilmelidir. Tarım işyeri olanlar harcama öteleme yapacağı zaman DeferringCount (Öteleme Ay Sayısı) parametresini kullanmalıdır. Gerekli taksit tanımlamaları için şube ile görüşülmelidir. DeferringCount (Öteleme Ay Sayısı): Sanal POS üzerinden gönderilen ay sayısı kadar işlemlerin yazılan ay kadar ötelenmesini sağlayan bilgidir. Tarım işyerlerinden Tohum Kart (547564 ile başlayan) ile harcama öteleme için kullanılmaktadır. Sadece tarım işyerleri için zorunlu tutulmaktadır. Tarım işyeri eğer harcama öteleme değil taksit yapmak istiyorsa sadece InstallmentCount (Taksit Sayısı) parametresinde taksit sayısını göndermelidir. Gerekli tanımlamalar için şube ile görüşülmelidir. Amount (Tutar): İşlem tutarının girildiği alandır. Bu alanda hiçbir noktalama işareti kullanılmadan ve gerçek tutarın 100 katı gönderilmelidir. (Örneğin; 102.65 TL için 10265, 1 TL için 100) DisplayAmount (Tutar Görünümü): Tutar (Amount) değeri ile aynı olacak şekilde gönderilmelidir. CurrencyCode (Para Kodu): Para birimidir, “0949” olarak gönderilmesi gerekmektedir. Sanal posla yalnızca TL ile işlem alınmaktadır. MerchantOrderId (Üye İşyeri Sipariş Numarası): İşlemin üye işyeri tarafında yer alan numarasıdır. Bu alana işyeri istediği sabit veya değişken değer atayabilmektedir. TransactionSecurity (İşlem Güvenliği): İşlemin yapılacağı güvenlik türü bilgisidir. Güvenli Ödeme işlemleri için sabit değer 3 gönderilmelidir. UserName (Api Kullanıcı Adı): https://kurumsal.kuveytturk.com.tr adresine login olarak kullanıcı işlemleri sayfasında API rolünde oluşturulan kullanıcı adıdır. (Yönetim - Kullanıcı İşlemleri- Kullanıcı Ekleme) Maksimum 10 karakter uzunluğunda, harf veya rakamdan oluşturulmalıdır. Türkçe karakter kullanılmamalıdır. Password (Api Şifresi): https://kurumsal.kuveytturk.com.tr adresine login olarak kullanıcı işlemleri sayfasında oluşturulan API kullanıcısının şifre bilgisidir. CardHolderName: Kart sahibi adı- soyadı bilgisi. 2-45 karakter uzunluğunda olmalıdır. DeviceChannel : DeviceData alanı içerisinde gönderilmesi beklenen işlemin yapıldığı cihaz bilgisi. 2 karakter olmalıdır. 01-Mobil, 02-Web Browser için kullanılmalıdır. Kuveyt Türk Katılım Bankası 2024 Sayfa 8 ClientIP : DeviceData alanı içerisinde gönderilmesi beklenen kart sahibinin işleme geldiği IP adres bilgisi. IPv4 adresi, ondalık sayılar nokta ile ayrılmış 4 grup biçiminde temsil edilir. Her setteki ondalık sayı 0-255 aralığındadır. Örnek IPv4 adresi: 1.12.123.255 BillAddrCity : CardHolderData alanı içerisinde gönderilmesi beklenen ödemede kullanılan kart ile ilişkili kart hamilinin fatura adres şehri. Maksimum 50 karakter uzunluğunda olmalıdır. BillAddrCountry: CardHolderData alanı içerisinde gönderilmesi beklenen ödemede kullanılan kart ile ilişkili kart hamilinin fatura adresindeki ülke kodu. Maksimum 3 karakter uzunluğunda olmalıdır. ISO 3166-1 sayısal üç haneli ülke kodu standardı kullanılmalıdır. BillAddrLine1 : CardHolderData alanı içerisinde gönderilmesi beklenen ödemede kullanılan kart ile ilişkili kart hamilinin teslimat adresinde yer alan sokak vb. bilgileri içeren açık adresi. Maksimum 150 karakter uzunluğunda olmalıdır. BillAddrPostCode: CardHolderData alanı içerisinde gönderilmesi beklenen ödemede kullanılan kart ile ilişkili kart hamilinin fatura adresindeki posta kodu. BillAddrState: CardHolderData alanı içerisinde gönderilmesi beklenen ödemede kullanılan kart ile ilişkili kart hamilinin fatura adresindeki il veya eyalet bilgisi kodu. ISO 3166-2'de tanımlı olan il/eyalet kodu olmalıdır. Email: CardHolderData alanı içerisinde gönderilmesi beklenen ödemede kullanılan kart ile ilişkili kart hamilinin iş yerinde oluşturduğu hesapta kullandığı email adresi. Maksimum 254 karakter uzunluğunda olmalıdır. Cc: CardHolderData alanı içerisinde yer alan MobilePhone içerisinde gönderilmesi beklenen ödemede kullanılan kart ile ilişkili kart hamilinin cep telefonuna ait ülke kodu. 1-3 karakter uzunluğunda olmalıdır. Subscriber : CardHolderData alanı içerisinde yer alan MobilePhone içerisinde gönderilmesi beklenen ödemede kullanılan kart ile ilişkili kart hamilinin cep telefonuna ait abone numarası. Maksimum 15 karakter uzunluğunda olmalıdır. 4.3. Banka Tarafında Dönen Cevap Bilgileri OrderId (İşlem Numarası): İşlemin Sanal Pos sisteminde kayıtlı numarasıdır. Banka Tarafında üretilmektedir. İade ve iptal işlemlerinde kullanılmaktadır. ProvisionNumber (Provizyon Numarası): Başarılı işlemlerde kart bankasının vermiş olduğu otorizasyon numarasıdır. Kart bankası tarafında üretilmektedir. İade ve iptal işlemlerinde kullanılmaktadır. RRN (Referans Numarası1): Pos bankası tarafında üretilen işlem referans numarasıdır. İade ve iptal işlemlerinde kullanılmaktadır. Kuveyt Türk Katılım Bankası 2024 Sayfa 9 Stan (Referans Numarası2): Pos bankası tarafında üretilen işlem referans numarasıdır. İade ve iptal işlemlerinde kullanılmaktadır. ResponseCode (Cevap Kodu): Genel kabul görmüş kart veya pos bankası cevabıdır. Başarılı işlemlerde “00” kodu verilmektedir. Her bir kod farklı bir cevabı bulunmaktadır. ResponseMessage (Cevap Mesajı): Genel kabul görmüş kart veya pos bankası cevabının açıklamasıdır. MD: Banka tarafından her işlem için oluşturulan değerdir. Ödemenin alınacağı Request 2 içerisinde gönderilmesi gerekmektedir. Not: Cevap kodu ve cevap mesajı listesi https://kurumsal.kuveytturk.com.tr adresindeki Yönetim Dokümantasyon alanında paylaşımdadır. 5. Entegrasyon Sanal Pos tarafından sunulan Güvenli Ödeme yöntemi için kullanılacak örnek bir entegrasyon işlemi bu kısımda anlatılmaktadır. • • • • • • • • • Üye işyeri kullanıcıdan kart bilgilerini alır. Kart, sipariş ve üye işyerine ait bilgileri içeren mesaj oluşturulur. Mesajda yer alacak Hashdata alanına dikkat edilmelidir. Bu mesaj yapısı XML formatındadır. Bir sonraki bölümde mesaj yapısı ve örnek mesaj yer almaktadır. Üye işyeri oluşturduğu XML mesajı Sanal Pos tarafından sunulan Sanal Pos Güvenli Ödeme Noktası (Kart Doğrulaması) noktasına HTTP POST yöntemi ile gönderir. Bu işlem sonucunda HTML yapısında bir cevap yer almaktadır. Üye işyeri bu HTML cevabı tarayıcıya iletmelidir. Sanal Pos tarafından gerçekleştirilecek işlemler sonrasında işleme ait sonuç XML mesaj şeklinde FailUrl ya da OkUrl’e HTTP Post ile iletilecektir. Bir sonraki bölümde mesaj yapısı ve örnek mesaj yer almaktadır. Güvenli Ödeme şifre ekranı ile sadece kart doğrulama işlemi yapılmaktadır, otorizasyon (ödemenin alınması) verilmemektedir, otorizasyon (ödeme) almak için onay Sanal Pos Güvenli Ödeme Onaylama (Otorizasyon Alınması) adresine istekte bulunmanız gerekmektedir. Üye işyeri FailUrl'e veya OkUrl'e gelecek cevaba göre kontrollerini yapar, dilerse kullanıcıya gösterebilir. Eğer işlem sonucu başarılı olarak mesaj OkUrl'e iletildiyse (Response Code “00” ve Response Message “Kart Doğrulandı”) üye işyeri ödeme işlemini sonlandırmak için Sanal Pos Güvenli Ödeme Onaylama (Otorizasyon Alınması) adresine ödeme mesajı göndermelidir. Gönderilecek mesajda, bu noktada gelen cevapta yer alan "MD" değeri ile birlikte ilk aşamada gönderilen üye işyeri ve sipariş bilgileri gönderilmelidir. Sanal Pos Güvenli Ödeme Onaylama (Otorizasyon Alınması) adresine gönderilen mesaj Sanal Pos servisi tarafından işlenir ve XML cevap verilir. XML cevapta yer alan ResponseCode değeri "00" ve Kuveyt Türk Katılım Bankası 2024 Sayfa 10 Response Message “Otorizasyon verildi.” olduğu durumda ödeme işlemi başarılı gerçekleşmiş olmaktadır. 5.1. Kullanılan Mesaj Yapıları 5.1.1. Satış İşlemi Mesaj Örneği – Kart Doğrulaması (Request 1) // 1.0.0 Eylül 2022’de sonlandırıldı. TDV2.0.0 http://localhost/php//ThreeDModetest/Approval.php http://localhost/php//ThreeDModetest/Fail.php TJcp1k5UUT/TSa5X2m0+82E9I/o= 496 400235 02 12.22.156.43 İstanbul 792 XXX Mahallesi XXX Caddesi No 55 Daire 1 34000 40 xxxxx@gmail.com 90 1234567899 apitest **************** ** ** *** Test Troy Sale 0 500 500 0949 20201221 Kuveyt Türk Katılım Bankası 2024 Sayfa 11 3 5.1.2.Satış İşlemi Mesaj Örneği Banka Cevabı (Response 1) 40790217 http://localhost/php//ThreeDModetest/Approval.php http://localhost/php//ThreeDModetest/Fail.php 496 0 0 apiuser poCqMathhevCYY1LVNbWCQWbC5I= 4033********0327 2159 0 100 100 20201221 0 949 0 0 0 0 3 true false 00 Kart doğrulandı. 40790217 0001-01-01T00:00:00 20201221 q3HpRgAO4xPP5UVYBg8EcVtO+sQ= BUdzLdTOnnrFP1/q1C/EgfrVxHvdvDtx2MuEusn+lB9My5kmogvb4JreoUYD1++6 2d8429b16f3843e3a9052cc4a772986f 202012211058907118850000001 Kuveyt Türk Katılım Bankası 2024 Sayfa 12 5.1.3. Satış İşlemi Onay Mesaj Örneği – Ödeme Alınması (Request 2) // 1.0.0 TDV2.0.0 ANcybxW/c1G39+RMstZ3ROYakO8= 496 400235 apitest Sale 0 100 20201221 3 MD BUdzLdTOnnrFP1/q1C/EgfrVxHvdvDtx2MuEusn+lB9My5kmogvb4JreoUYD1++6 5.1.4.Ödeme İşlem Sonucu Mesaj Yapısı (Response 2) 40790217 http://localhost/php//ThreeDModetest/Approval.php http://localhost/php//ThreeDModetest/Fail.php 496 0 400235apitest poCqMathhevCYY1LVNbWCQWbC5I= 4033********0327 2159 0 100 0 20201221 0 949 Kuveyt Türk Katılım Bankası 2024 Sayfa 13 0 0 0 0 3 0 true false 412371 035617458943 458943 00 OTORİZASYON VERİLDİ 40790217 2020-12-21T17:22:45.383 20201221 q4RhSZcSM+EbvCrNVb+kb0nZ/Po= 202012211078954039910000001 5.2. Tarım İşyeri 5.2.1. Satış İşlemi Mesaj Örneği – Kart Doğrulaması (Request 1) – Tarım İşyeri // 1.0.0 TDV2.0.0 http://localhost/php//ThreeDModetest/Approval.php http://localhost/php//ThreeDModetest/Fail.php TJcp1k5UUT/TSa5X2m0+82E9I/o= 496 400235 apitest **************** 02 12.22.156.43 Kuveyt Türk Katılım Bankası 2024 Sayfa 14 İstanbul 792 XXX Mahallesi XXX Caddesi No 55 Daire 1 34000 40 xxxxx@gmail.com 90 1234567899 ** ** *** Test Troy Sale 0 3 500 500 0949 20201221 3 5.2.2.Satış İşlemi Mesaj Örneği Banka Cevabı (Response 1) - Tarım İşyeri 40790217 http://localhost/php//ThreeDModetest/Approval.php http://localhost/php//ThreeDModetest/Fail.php 496 0 0 apiuser poCqMathhevCYY1LVNbWCQWbC5I= 4033********0327 2159 0 100 100 20201221 0 Kuveyt Türk Katılım Bankası 2024 Sayfa 15 949 0 0 0 0 3 true false 00 Kart doğrulandı. 40790217 0001-01-01T00:00:00 20201221 q3HpRgAO4xPP5UVYBg8EcVtO+sQ= BUdzLdTOnnrFP1/q1C/EgfrVxHvdvDtx2MuEusn+lB9My5kmogvb4JreoUYD1++6 2d8429b16f3843e3a9052cc4a772986f 202012211058907118850000001 5.2.3. Satış İşlemi Onay Mesaj Örneği – Ödeme Alınması (Request 2) - Tarım İşyeri // 1.0.0 Eylül 2022’de sonlandırıldı. TDV2.0.0 ANcybxW/c1G39+RMstZ3ROYakO8= 496 400235 apitest Sale 0 100 20201221 3 MD BUdzLdTOnnrFP1/q1C/EgfrVxHvdvDtx2MuEusn+lB9My5kmogvb4JreoUYD1++6 Kuveyt Türk Katılım Bankası 2024 Sayfa 16 5.2.4.Ödeme İşlem Sonucu Mesaj Yapısı (Response 2) - Tarım İşyeri 40790217 http://localhost/php//ThreeDModetest/Approval.php http://localhost/php//ThreeDModetest/Fail.php 496 0 400235apitest poCqMathhevCYY1LVNbWCQWbC5I= 4033********0327 2159 0 3 100 0 20201221 0 949 0 0 0 0 3 0 true false 412371 035617458943 458943 00 OTORİZASYON VERİLDİ 40790217 2020-12-21T17:22:45.383 Kuveyt Türk Katılım Bankası 2024 Sayfa 17 20201221 q4RhSZcSM+EbvCrNVb+kb0nZ/Po= 202012211078954039910000001 Not: Ödeme işlemine ait cevap mesajının içerisinde yer alan VPOSMessage alanında, üye işyerlerinin ödeme işlemi için gönderdikleri mesaj yer almaktadır. Not: OkUrl veya FailUrl e iletilecek bu mesaj AuthenticationResponse altında UrlEncoded olacak şekilde gönderilmektedir. Mesajı kullanmak için gelen formun içinde AuthenticationResponse anahtarıyla gönderilen değeri UrlDecode ile çözünüz. (Örneğin .NET için; System.Web.HttpUtility.UrlDecode(Request.Form["AuthenticationResponse"]) şeklinde kod parçası kullanınız.) 6. HashData Hesaplamaları İşyerine gelen cevabın Kuveyt Türk Sanal POS tarafından gönderildiğinin kontrol edilebilmesi için HashData değeri yer almaktadır. Üye işyerinin kendi oluşturduğu HashData ile Kuveyt Türk Sanal POS tarafında Hashdata hesaplamasından beklediği değerin eşleşmesi gerekmektedir. Hashdata hesaplamasında kullandığınız değerlerin banka tarafındaki değerlerden farklı olması durumunda "Şifrelenen veriler (Hashdata) uyuşmamaktadır." hatası alınmaktadır. Banka tarafında gönderilen Cevap mesajı Hash hesaplamasında kullanılan parametreler şöyledir: MerchantOrderId, RRN, ResponseCode, OrderId, hashPassword Not: “Response 1” banka cevap mesaj yapısında RRN üretilmediğinden hash hesaplamasına dâhil edilmemektedir. MerchantOrderId, ResponseCode, OrderId, hashPassword parametreleri kullanılmaktadır. Üye işyerinin satış işleminde göndermesi gereken Hash hesaplamasında kullanılan parametreler şöyledir: MerchantId, MerchantOrderId, Amount, OkUrl, FailUrl, UserName, hashPassword Not: Satış İşlemi Onay Mesaj (Request 2) yapısında sayfa yönlendirmesi yapılmadığından Hash hesaplamasında OkUrl ve FailUrl alanları dahil edilmeyecektir. Request 2 için; MerchantId, MerchantOrderId, Amount, UserName, HashPassword Hesaplama $Password=""; // Web Yönetim ekranlarından oluşturulan Api rolündeki kullanıcı şifresi $HashedPassword = base64_encode(sha1($Password,"ISO-8859-9")); //md5($Password); Kuveyt Türk Katılım Bankası 2024 Sayfa 18 $HashData=base64_encode(sha1($MerchantId.$MerchantOrderId.$Amount.$OkUrl.$FailUrl.$UserName .$HashedPassword , "ISO-8859-9")); 7. Sanal Pos Güvenli Ödeme Noktası Adresleri (Güncel) Sanal Pos Güvenli Ödeme Noktası – Kart Doğrulanması (Production) : https://sanalpos.kuveytturk.com.tr/ServiceGateWay/Home/ThreeDModelPayGate Sanal Pos Güvenli Ödeme Onaylama – Ödeme Alınması (Production) : https://sanalpos.kuveytturk.com.tr/ServiceGateWay/Home/ThreeDModelProvisionGate 8. Test Ortam Bilgileri UserId = "400235"; // Müşteri Numarası MerchantId = "496" ; // Mağaza Numarası Api Bilgileri UserName="apitest"; Password="api123"; Test Kart Bilgileri Kart No: # 5188’9619’3919’2544# CVV: 929 Expirydate: 06/25 Kart Doğrulama Şifresi: 123456 Sanal Pos 3D Model Ödeme Noktası Adresi – Kart Doğrulama (Test): https://boatest.kuveytturk.com.tr/boa.virtualpos.services/Home/ThreeDModelPayGate Sanal Pos 3D Model Ödeme Onaylama Adresi – Ödeme Alma (Test): https://boatest.kuveytturk.com.tr/boa.virtualpos.services/Home/ThreeDModelProvisionGate Not: Test ortamında alınacak herhangi bir hatada bankaya bilgi verebilirsiniz. Mail adresi: sanalposdestek@kuveytturk.com.tr Kuveyt Türk Katılım Bankası 2024 Sayfa 19 Kuveyt Türk Katılım Bankası 2024 Sayfa 20