• Tami Sanal POS

3D'li Ön Otorizasyon İşlemi Genel Açıklama

Tami üzerinden gerçekleştirilmek istenen 3d'li ödeme için belirtilen tutar kadar karttan bakiyenin bloke edilmesini sağlar. İşlem ilk olarak 3d doğrulama adımından başlatılır. Başarılı sonuçlanan 3d doğrulama sonrasında 3d tamamlama adımında işlem gerçek bir ön otorizasyon işlemi gerçekleştirilmiş olur.

Ön otorizasyon işleminde karttan tutar bloke edilmiş olur. Ön otorizasyon kapama işlemi ile birlikte karttan ödeme alınmış olur.

Test/Prod Ortamları API Kullanıcı Bilgisi

Tami üzerinden gerçekleştirilen Sanal POS işlemleri için üye işyerleri test ortamında gerçekleştirmek istedikleri kontrolleri aşağıdaki tabloda verilen üye işyeri bilgilerini kullanabilirler.

Üretim ortamında Tami üzerinden gerçekleştirilecek Sanal POS işlemleri için başvuru yapılarak üye işyeri numarası alınır ve bu bilgilerle işlem geçirilir.

Sandbox test portaline https://sandbox-portal.tami.com.tr adresinden ulaşabilirsiniz. Aşağıda iletilen kullanıcılar ile test portale giriş yapıldığında bu kullanıcıya bağlı işyeri tarafından gerçekleştirilen işlemleri görüntülenebilir. İşlemler iptal/iade edilebilir.

Kullanıcı Telefon Numarası Kullanıcı Şifre Sms / Email Otp İşyeri Numarası Terminal Numarası Secret Key
5346484700 147850 147852 77006950 84006953 0edad05a-7ea7-40f1-a80c-d600121ca51b
5346484709 147850 147852 77006951 84006954 c8581bb6-a4b2-4925-8c94-529fc651399e
5346484803 147850 147852 77006952 84006955 ff7d4895-0c32-4f48-86ab-fb9ecca9f3d7
5346484807 147850 147852 77006953 84006956 33124ff0-0b19-4cf9-b002-13a35eae865b
5346484800 147850 147852 77006954 84006957 7daf9631-e136-4164-9ddb-dd1c02df851d
5346484808 147850 147852 77006956 84006959 fe6f3fff-0434-4932-a27d-bb3dac9de49d

Hash Hesaplama

Bir çok işlem tipi için gönderilen isteğin header bilgisine PG-Auth-Token eklenmelidir. PG-Auth-Token değeri “MerchantNumber:TerminalNumber:Hash” değerlerinden oluşur.

Burada hash hesabı yapılırken üye işyerine ait merchantNumber, terminalNumber ve secretKey bilgileri sha256 ile hashleyip stringe çevrilerek elde edilir.

public class SHA256Example {\n public static String sha256(Long merchantNumber, Long terminalNumber, String secretKey) {\n String text = merchantNumber.toString() + terminalNumber.toString() + secretKey;\n try {\n MessageDigest digest = MessageDigest.getInstance(\"SHA-256\");\n byte[] hash = digest.digest(text.getBytes(StandardCharsets.UTF_8));\n String sha256Hex = DatatypeConverter.printBase64Binary(hash);\n return sha256Hex;\n } catch (NoSuchAlgorithmException e) {\n e.printStackTrace();\n return null;\n }\n }\n }

TAMİ Test Portalı Bilgileri

Tami test portalına https://sandbox-portal.tami.com.tr adresinden erişebilirsiniz. Bu adresten yukarıda iletilen kullanıcılar ile portal ekranını görüntüleyebilirsiniz. 

Üretim ortamı bilgileriniz için https://portal.tami.com.tr adresinden üye olabilir veya e-ticaret destek birimine başvurabilirsiniz.

3D'li Ön Otorizasyon İşlemi API Bilgileri

Test ortamında yapılacak çalışmalarda "https://sandbox-paymentapi.tami.com.tr/payment/pre-auth" url'i kullanılacaktır.

Üretim ortamında yapılacak çalışmalarda ise "https://paymentapi.tami.com.tr/payment/pre-auth" url'i kullanılacaktır.

İstek Parametreleri ve Açıklamaları

Sanal POS 3D’siz Peşin/Taksitli Satış işlemleri için gerekli olan istek yapısı aşağıdaki tabloda belirtilmiştir. İstek mesajındaki bilgi ve açıklamalar incelenmeli ve istek mesajı bu tabloda belirtilen kurallara göre sağlanmalıdır:

Parametre Adı Format Uzunluk (O)psiyonel / (Z)orunlu/ (Ş)artlı Açıklama
orderId String (2-36) Z Ödeme isteğinin Tami-müşteri arasındaki iletişiminde kullanılan tekil bir iletişim bilgisidir. Üye işyeri ve pos çifti için bu değer tekil olmalıdır.
amount Decimal Z İşlem tutarıdır. Küsurat ayracı nokta (.) ile yapılmalıdır.
currency String 3 Z İşlemin döviz kodunu belirtir. Örnek: TL için TRY gönderilmeli.
installmentCount Number Z Yapılmak istenen işlemin taksit bilgisidir. Peşin işlem için 1 gönderilmelidir. 0 gönderilmesi kabul edilmez.
paymentGroup String Z Ödeme grubu, varsayılan PRODUCT. 
paymentChannel enum  O Ödeme kanalı. Geçerli değerler enum içinde sunulmaktadır: WEB, MOBILE, MOBILE_WEB, MOBILE_IOS, MOBILE_ANDROID, MOBILE_WINDOWS, MOBILE_TABLET, MOBILE_PHONE
callbackUrl String Ş  İşlem 3d'li olarak yapılmak isteniyorsa gönderilmesi zorunludur. 3d doğrulama sonucunun döneceği adrestir. Üye işyerine ait bir adres olmalıdır.
card Object Z  
cvv String Z Ödemenin alınacağı kartın güvenlik kodu bilgisi.
expireMonth Number (1-12) Z Ödemenin alınacağı kartın son kullanma tarihi ay bilgisi.
expireYear Number 4 Z Ödemenin alınacağı kartın son kullanma tarihi yıl bilgisi.
holderName String 30 Z Ödemenin alınacağı kart sahibinin adı soyadı bilgisi.
number String (5-35) Z Ödemenin alınacağı kart numarası bilgisi.
billingAddress Object O  
address String 400 O Üye işyeri tarafındaki fatura adresi bilgisi.
emailAddress String O Üye işyerine ait mail bilgisi
city String 30 O Üye işyeri tarafındaki fatura adresi şehir bilgisi.
companyName String 100 O Üye işyerinin ticari unvan bilgisi.
country String 50 O Üye işyeri tarafındaki fatura adresi ülke bilgisi.
contactName String 30 O Üye işyeri tarafındaki fatura adresi, ad soyad bilgisi.
phone String O Üye işyeri tarafındaki alıcıya ait GSM numarası.
zipCode String 15 O Üye işyeri tarafındaki fatura adresi posta kodu.
district String 50 O Üye işyeri tarafındaki fatura adresi semt bilgisi.
shippingAddress Object O  
address String 400 O Üye işyeri tarafındaki teslimat adresi bilgisi.
emailAddress String O Üye işyerine ait mail bilgisi
city String 30 O Üye işyeri tarafındaki teslimat adresi şehir bilgisi.
country String 50 O Üye işyeri tarafındaki teslimat adresi ülke bilgisi.
contactName String 30 O Üye işyeri tarafındaki teslimat adresi, ad soyad bilgisi.
zipCode String 15 O Üye işyeri tarafındaki teslimat adresi posta kodu bilgisi.
district String 50 O Üye işyeri tarafındaki teslimat adresi semt bilgisi.
buyer Object Z Üye işyeri tarafındaki alıcıya ait bilgileri içerir.
ipAddress String Z Üye işyeri tarafındaki alıcıya ait ip adresidir. Alıcının gerçek ip adresi iletilmesi gerekmektedir.
buyerId String 50 Z Üye işyeri tarafındaki alıcıya ait id bilgisidir.
name String 30 Z Üye işyeri tarafındaki alıcıya ait ad bilgisidir.
surName String 30 Z Üye işyeri tarafındaki alıcıya ait soyad bilgisidir.
identityNumber String 11 O Üye işyeri tarafındaki alıcıya ait kimlik (TCKN) numarası.
city String 50 O Üye işyeri tarafındaki alıcıya ait şehir bilgisi.
country String 50 O Üye işyeri tarafındaki alıcıya ait ülke bilgisi.
emailAddress String Z Üye işyeri tarafındaki alıcıya ait e-posta bilgisi. E-posta adresi alıcıya ait geçerli ve erişilebilir bir adres olmalıdır.
phoneNumber String Z Üye işyeri tarafındaki alıcıya ait GSM numarasıdır
registrationAddress String 400 O Üye işyeri tarafındaki alıcıya ait kayıt adresi.
zipCode String 15 O Üye işyeri tarafındaki alıcıya ait posta kodu.
registrationDate Date O Üye işyeri tarafındaki alıcıya ait kayıt tarihi. Tarih formatı 2015-09- 17 23:45:06 şeklinde olmalıdır.
lastLoginDate Date O Üye işyeri tarafındaki alıcıya ait son giriş tarihi. Tarih formatı 2015- 09-17 23:45:06 şeklinde olmalıdır.
basket O  
basketId String 50 Ş Üye işyeri tarafındaki sepete ait id. Basket içerisinde item iletilirse basketId gönderilmesi zorunlu olur.
basket/basketItems List 0  
itemId String 50 Ş Üye işyeri tarafındaki sepetteki ürüne ait id. Basket içerisinde item iletilirse itemId gönderilmesi zorunlu olur.
itemType String 50 Ş Üye işyeri tarafındaki sepetteki ürüne ait tip. Geçerli enum değerler: PHYSICAL ve VIRTUAL. Basket içerisinde item iletilirse itemType gönderilmesi zorunlu olur.
name String 50 Ş Üye işyeri tarafındaki sepetteki ürüne ait ismi. Basket içerisinde item iletilirse name gönderilmesi zorunlu olur.
category String 50 O Üye işyeri tarafındaki sepetteki ürüne ait kategori .
subCategory String 100 O Üye işyeri tarafındaki sepetteki ürüne ait alt kategori.
unitPrice Decimal min 0.0 O Üye işyeri tarafındaki sepetteki ürünün tekil tutarıdır.
totalPrice Decimal min 0.0 Ş Üye işyeri tarafındaki sepetteki ürüne ait toplam tutar. 0 ve 0’dan küçük olamaz, tutarlar toplamı sepet tutarına (amount) eşit olmalıdır. Unitprice * numberOfProducts = totalPrice olmalı. Basket objesi içerisinde item iletilirse totalPrice gönderilmesi zorunlu olur.
numberOfProducts Number 1-99999 O Üye işyeri tarafındaki sepetteki ürünün adedidir. 
securityHash String Z Dokumanda belirtilen şekilde hesaplanıp iletilmesi beklenen değerdir. Eksik veya hatalı iletilirse işlem bankaya yönlendirilmez, hata verilir.

3D'li Ön Otorizasyon API İsteği Örneği

{\n \"amount\": 15,\n \"orderId\": \"order\",\n \"currency\": \"TRY\",\n \"installmentCount\": 1,\n \"card\": {\n \"holderName\": \"Kemal Sunal\",\n \"cvv\": \"\",\n \"expireMonth\": 4,\n \"expireYear\": 2026,\n \"number\": \"4824910501747014\"\n },\n \"billingAddress\": {\n \"emailAddress\": \"email@email.com\",\n \"address\": \"Nisbetiye Barbaros Bulvarı Boulevard, No:96, 34340 Beşiktaş/İstanbul\",\n \"city\": \"İstanbul\",\n \"companyName\": \"SirketAdı\",\n \"country\": \"Türkiye\",\n \"district\": \"Bebek Mah.\",\n \"contactName\": \"İsim Soyisim\",\n \"phoneNumber\": \"05364604016\",\n \"zipCode\": \"343400\"\n },\n \"shippingAddress\": {\n \"emailAddress\": \"email@email.com\",\n \"address\": \"Nisbetiye Barbaros Bulvarı Boulevard, No:96, 34340 Beşiktaş/İstanbul\",\n \"city\": \"İstanbul\",\n \"companyName\": \"SirketAdı\",\n \"country\": \"Türkiye\",\n \"district\": \"Levent\",\n \"contactName\": \"İsim Soyisim\",\n \"phoneNumber\": \"05346484777\",\n \"zipCode\": \"3434221\"\n },\n \"buyer\": {\n \"ipAddress\": \"192.168.1.70\",\n \"buyerId\": \"678654\",\n \"name\": \"Adı\",\n \"surName\": \"Soyadı\",\n \"identityNumber\": 28629160374,\n \"city\": \"İstanbul\",\n \"country\": \"Türkiye\",\n \"zipCode\": \"348222\",\n \"emailAddress\": \"email@email.com\",\n \"phoneNumber\": \"05364609963\",\n \"registrationAddress\": \"Ortaköy Mah. Ulus Sok. Beşiktaş\",\n \"lastLoginDate\": \"2022-11-05T13:39:11.332\",\n \"registrationDate\": \"2022-10-11T12:59:11.332\"\n },\n \"basket\": {\n \"basketId\": \"6489494\",\n \"basketItems\": [\n {\n \"itemId\": \"7448\",\n \"name\": \"basketname1\",\n \"itemType\": \"PHYSICAL\",\n \"numberOfProducts\": 1,\n \"totalPrice\": 15,\n \"unitPrice\": 15\n }\n ]\n },\n \"paymentGroup\": \"PRODUCT\",\n \"callbackUrl\": \"https://gbtunelemulator-d.fw.garantibbva.com.tr/secure3d\", \n \"securityHash\": \"647494994F8494H94894849K849==\"\n}

3D'li Ön Otorizasyon API İstek Cevabı Örneği

{\n \"success\": true,\n \"systemTime\": \"2024-03-20T09:47:35.290917608\",\n \"correlationId\": \"correlation4584\",\n \"orderId\": \"order\",\n \"securityHash\": \"68493Gedy8F9302HH94040==\",\n \"amount\": 15,\n \"currency\": \"TRY\",\n \"installmentCount\": 1,\n \"card\": {\n \"binNumber\": \"48249105\",\n \"maskedNumber\": \"4824-9105-xxxx-xx14\",\n \"cardBrand\": \"Garanti\",\n \"cardOrganization\": \"VISA\",\n \"cardType\": \"CREDIT\"\n }\n}

3D'li Ön Otorizayon İstek Cevabı Parametreleri ve Açıklamaları

Parametre Adı Format Açıklama
 success String True dönmesi durumunda satış başarılıdır. False dönmesi durumunda hata almıştır. Hata detayı errorCode ve errorMessage alanlarında paylaşılır.
systemTime DateTime İşlem tarihi
correlationId String İşlem numarası
orderId String Sipariş numarası
amount Number İşlem tutarı
currency String İşlem para birimi
card/binNumber String Kartın ilk 8 hanesi
card/maskedNumber String Maskeli kart numarası
card/cardBrand String Kart markası
card/cardOrganization String Kart organizasyonu
card/cardType String Kart tipi
threeDSHtmlContent Integer 3d doğrulama sayfasına yönlendirecek html content bilgisidir. Content içeriği base 64'te decode edilerek Html elde edilir.
errorCode String Hata kodu
errorMessage String Hata mesajı
securityHash String İşlemin sonucunun doğru kaynaktan geldiğini belirlemek için kullanılacak değerdir. Dokumanda nasıl hesaplanması gerektiği belirtilmiştir.

3D Doğrulama

3D'li Ön Otorizasyon başlatma sonucunda elde edilen HTML data ile bankanın 3d doğrulama ekranı görüntülenecektir. Kart sahibi cep telefonuna gelen şifreyi girdikten sonra otomatik olarak callbackUrl parametresinde belirttiğiniz adrese yönlenecektir. Tami bu adrese aşağıdaki değerleri post edecektir.

3D doğrulama sonucu başarılı olduğunda karttan henüz para çekilmemiştir. Cevapta dönen succes alanı true olduğunda işlemi ödemeye çevirmek için bir sonraki 3D’li satış işlemi tamamlama adımına geçebilirsiniz. 3D'li satış işlemi tamamlanmayan işlemler için karttan ödeme alınmaz.

3D Doğrulama Cevabı Parametreleri ve Açıklamaları

Parametre Adı Format Açıklama
cardBrand String Kart Markası
cardOrganization String Kart Organizasyonu
cardType String  Kart Tipi
currencyCode String İşlem Para Birimi
hashedData String Cevapta dönen bilgilerin doğruluğunu kontrol etmek için kullanılacak değer
installmentCount Number İşlem Taksit Sayısı
maskedNumber Number Maskeli olarak kart numarası
mdStatus String Bilgilendirme amaçlı dönen mdStatus değeridir. Başarılı durumlar için 1, başarısız için ise 0, 2, 3, 4, 5, 6, 7, 8 olarak dönebilir.
orderId String Sipariş numarası
success String Yapılan 3d doğrulama işleminin sonucunu bildirir. İşlem başarılı ise true, hatalı ise false döner.
systemTime DateTime İşlem Tarihi
txnAmount Number İşlem Tutarı

3D Doğrulama cevabında dönen Success alanının false olması durumunda aşağıdaki tablo hatanın sebebi ile ilgili yardımcı olacaktır.

mdStatus Açıklama
mdStatus =0 3-D Secure imzası geçersiz veya doğrulama
mdStatus =2 Kart sahibi veya bankası sisteme kayıtlı değil
mdStatus =3 Kartın bankası sisteme kayıtlı değil
mdStatus =4 Doğrulama denemesi, kart sahibi sisteme daha sonra kayıt olmayı seçmiş
mdStatus =5 Doğrulama yapılamıyor
mdStatus =6 3-D Secure hatası
mdStatus =7 Sistem hatası
mdStatus =8 Bilinmeyen kart no

HashedData Hesaplaması

3D Doğrulama cevabında dönen bilgilerin doğru kaynaktan geldiğini doğrulamak için aşağıda iletilen alanlara göre hashedData hesaplayarak response’daki bu bilgi ile karşılaştırabilirsiniz. SecretKey üye işyerine ait her pos için farklıdır.

HashedData hesaplanırken aşağıdaki tüm parametreleri verilen sıra ile yan yana getirilerek bir data oluşturulur. Üye işyerine ait olan secretKey bilgisi HMAC sha256 ile hashlenerek secretKeySpec elde edilir. Aşağıdaki generatorda belirtilen formatta iki veri sıralanır. Base 64 te encode edilir ve şifrelenmiş hashedData elde edilir.

NOT: Peşin işlemlerde “InstallmentCount” bilgisinin 1 olarak gönderilmesi beklenir. Bu bilgi ile hashedData ya eklenir.

HashedData hesaplamasında kullanılan parametreler;

cardOrg+cardBrand+cardType+maskedNumber+installmentCount+currency+originalAmount+orderID+systemTime+status (success alanı)

HashedData hesaplamasında kullanılacak generator aşağıda verilmiştir.

public static String responseHashGenerate(String systemTime, String status, String maskedNumber, Order order,\n String secretKey) {\n\n String data = order.getCardOrg() + order.getCardBrand() + order.getCardType() +\n maskedNumber + order.getInstallmentCount() + order.getCurrency() +\n order.getOriginalAmount() + order.getOrderId() + systemTime + status;\n String result = \"\";\n try {\n Mac sha256_HMAC = Mac.getInstance(\"HmacSHA256\");\n SecretKeySpec secret_key = new SecretKeySpec(secretKey.getBytes(\"UTF-8\"), \"HmacSHA256\");\n sha256_HMAC.init(secret_key);\n\n result = Base64.encodeBase64String(sha256_HMAC.doFinal(data.getBytes(\"UTF-8\")));\n\n } catch (Exception e) {\n log.error(\"Hash can not be generated \", e);\n }\n return result;\n}

3D'li Ön Otorizasyon İşlemi Tamamlama Hakkında

Tami üye işyerleri tarafından gerçekleştirilen başarılı olarak 3d doğrulaması yapılmış işlemlerin tamamlaması için kullanılır. Bu servis çağırılarak 3d tamamlanması yapıldığında karttan belirtilen tutar bloke edilmiş olur. Sonrasında ön otorizasyon kapama yapılarak işlem finansallaştırılmalıdır.

3D'li Ön Otorizasyon İşlemi Tamamlama API Bilgileri

Test ortamında yapılacak çalışmalarda "https://sandbox-paymentapi.tami.com.tr/payment/complete-3ds" url'i kullanılacaktır.

Üretim ortamında yapılacak çalışmalarda ise "https://paymentapi.tami.com.tr/payment/complete-3ds" url'i kullanılacaktır.

3D'li Ön Otorizasyon İşlemi Tamamlama İstek Parametreleri ve Açıklamaları

Alan Format Uzunluk (O)psiyonel / (Z)orunlu Açıklama
orderId String (2-36) Z 3d doğrulaması başarılı tamamlanmış sipariş numarası bilgisi
securityHash String Z Dokumanda belirtilen alanlara göre hesaplanıp iletilmesi beklenen değerdir. Eksik veya hatalı iletilirse işlem bankaya yönlendirilmez, hata verilir.

3D'li Ön Otorizasyon İşlemi Tamamlama API İstek Örneği

{ \n \"orderId\": \"3dtamamlama\",\n \"securityHash\": \"47hsj84993jow90500rK94To=\"\n}

3D'li Ön Otorizasyon İşlemi Tamamlama API İstek Cevabı Örneği

{\n \"success\": true,\n \"systemTime\": \"2023-08-10T11:40:02.299\",\n \"correlationId\": \"TEST9962\",\n \"orderId\": \"3dtamamlama\",\n \"securityHash\": \"7hdsH49k3kd0Yosnhe==\",\n \"amount\": 415,\n \"currency\": \"TRY\",\n \"installmentCount\": 1,\n \"card\": {\n \"binNumber\": \"48249105\",\n \"maskedNumber\": \"4824-9105-xxxx-xx14\",\n \"cardBrand\": \"Garanti\",\n \"cardOrganization\": \"VISA\",\n \"cardType\": \"CREDIT\"\n }\n}

3D'li Ön Otorizasyon İşlemi Tamamlama İstek Cevabı Parametreleri ve Açıklamaları

Parametre Adı Format Açıklama
 errorCode String Hata kodu
errorMessage String Hata mesajı
success String True dönmesi durumunda satış başarılı, false dönmesi durumunda hata alınmıştır. Hata detayı error code ve error message alanlarında paylaşılır
systemTime dateTime İşlem tarihi
correlationId String İşlem numarası
orderId String Sipariş numarası
amount Number İşlem tutarı
currency String İşlem para birimi
installmentCount Number İşlem taksit sayısı
card/binNumber String Kartın ilk 8 hanesi
card/maskedNumber String Maskeli kart numarası
card/cardBrand String Kart markası
card/cardOrganization String Kart organizasyonu
card/cardType String Kart tipi
securityHash String  İşlemin sonucunun doğru kaynaktan geldiğini belirlemek için kullanılacak değerdir. Dokumanda nasıl hesaplanması gerektiği belirtilmiştir.

Security Hash Hesaplama

Yapılacak servis isteklerinde ve gelen servis cevaplarında securityHash alanının hesaplanması için buradaki dokümantasyondan yararlanabilirsiniz. 

Hata Kodları

Hata kodları listesine bu sayfadan ulaşabilirsiniz.

Test Kartları

Test kartları listesine bu sayfadan ulaşabilirsiniz.

Tüm soru ve destek taleplerinde yanındayız.

Soru Sor Soru Sor