• Tami Sanal POS

Tami Sanal POS

Filtrele

3D’li Satış İşlemi Genel Açıklama

3D’li satış işlemi, Tami üzerinden 3D Secure doğrulaması ile ödeme almanızı sağlar. İşlem iki adımdan oluşur: önce 3D’li satış işlemini başlatırsınız, bu adımın sonucunda size bir HTML içerik (content) döner; bu içeriği Base64'ten çözerek elde ettiğiniz HTML sayfasına müşterinizi yönlendirirsiniz. Müşteri doğrulama kodunu girdikten sonra 3D doğrulama sonucu belirlenir. Doğrulama başarılı olursa, işlemi satışa çevirmek için 3D’li satış işlemini tamamlama servisini çağırmanız gerekir.

Tami Test/Prod Portal Bilgileri

Entegrasyonunuzu canlıya almadan önce, gerçek para hareketi oluşturmadan test edebilmeniz için Tami Test Portalı’nı kullanabilirsiniz.

Test Portalı adresi: https://sandbox-portal.tami.com.tr

Test portalına giriş yaparak işlemlerinizi görüntülemek ve gerektiğinde iptal/iade yapmak isterseniz, size özel bir test portalı kullanıcısı tanımlanması gerekir. Bunun için TeknikDestek@tami.com.tr adresinden destek ekibimize ulaşabilirsiniz.

Prod Portalı adresi: https://portal.tami.com.tr

Üretim ortamı bilgileriniz için bu adresten üye olabilir veya e-ticaret destek birimimize başvurabilirsiniz.

Tami Test / Prod Api Kullanıcıları

Tami API’lerini entegre ederken iki farklı ortam kullanılır: Sandbox (Test) ve Prod (Üretim).

  • Test (Sandbox) Ortamı

Gerçek para hareketi oluşturmadan entegrasyonunuzu test etmenizi sağlar. İstekleriniz test endpoint’lerine gönderilir ve yukarıdaki Tami Test Portalı üzerinden takip edilebilir.

Sandbox ortamında API üzerinden test işlemi gönderebilmeniz için kullanabileceğiniz bilgiler aşağıdadır:

Alan Değer
Merchant Number 77006950
Terminal Number 84006953
Secret Key 0edad05a-7ea7-40f1-a80c-d600121ca51b
  • Prod (Üretim) Ortamı

Canlı işlemlerin gerçekleştiği, gerçek ödemelerin alındığı ortamdır.

Üretim ortamı bilgileriniz için https://portal.tami.com.tr üzerinden üye olabilir ya da e-ticaret destek birimimize başvurabilirsiniz.

PG Auth Token Oluşturma

Sanal POS servislerine gönderilen isteklerde, header içerisinde PG-Auth-Token alanının gönderilmesi zorunludur.

PG-Auth-Token, aşağıdaki formatta oluşturulur:

MerchantNumber:TerminalNumber:Hash

Hash değeri; işyerinize ait Merchant numarası, Terminal numarası ve Secret Key bilgilerinin arka arkaya (sırasıyla) birleştirilip SHA-256 algoritmasıyla hashlenmesi ve elde edilen sonucun Base64 formatına çevrilmesiyle oluşturulur.

Aşağıda bu hesaplamayı gösteren örnek bir Java kod bloğu yer almaktadır:

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}\n

Oluşturduğunuz Hash değerini, Merchant numarası ve Terminal numarası ile yukarıdaki formatta birleştirerek PG-Auth-Token header değerini oluşturabilirsiniz.

3D’li Satış İşlemi Başlatma Hakkında

3D’li bir satış işleminin ilk adımıdır. İşlem güvenliği açısından, bu adımda da isteğinizdeki bilgiler Tami’ye açık şekilde iletilmez; üye işyerinize ait callbackUrl adresi dahil tüm bilgileri içeren istek, imzalanarak şifrelenir ve signedRequest alanı ile gönderilir. İşlem sonucunda dönen yanıt da aynı şekilde şifrelenmiş olup signedResponse alanı içerisinde iletilir. signedResponse değerini çözümlediğinizde, içerisinde yer alan HTML içeriğe (content) ulaşırsınız; bu içeriği Base64'ten çözerek elde ettiğiniz HTML sayfasına müşterinizi yönlendirirsiniz. Müşteri burada doğrulama kodunu girer ve 3D doğrulama sonucu belirlenir.

3D’li Satış İşlemi Başlatma API Bilgileri

3D’li satış işlemini başlatmak için kullanılacak endpoint bilgileri aşağıdadır:

Ortam Endpoint
Test (Sandbox) https://sandbox-paymentapi.tami.com.tr/api/v0/payment/auth
Üretim (Prod) https://paymentapi.tami.com.tr/api/v0/payment/auth

İsteklerinizi POST metodu ile, çalıştığınız ortama (test/üretim) uygun endpoint’e göndermeniz gerekir.

3D’li Satış İşlemi Başlatma İsteğinin Atılma Yöntemi

3D’li satış işlemini başlatırken de, gönderilen isteğin gövdesinde (body) değerler açık bir şekilde değil, imzalanarak şifrelenmiş tek bir değerin iletilmesi beklenir. Bu değer, signedRequest alanı ile gönderilir.

Tami tarafından dönen response da aynı şekilde imzalanarak şifrelenmiş olup signedResponse alanı içerisinde iletilir.

Bunlara ek olarak, header alanında da aşağıdaki bilgilerin gönderilmesi gerekir:

  • PG-Auth-Token: Nasıl hesaplanacağı yukarıdaki “PG Auth Token Oluşturma” başlığında anlatılmıştır.
  • CorrelationId: Her istek için tekil (unique) olması gereken, değişken bir değerdir.
  • PG-Api-Version: v4 olarak iletilmesi gerekir.

3D’li Satış İşlemi Başlatma İmzalanarak Şifrelenecek Parametreler ve Açıklamaları

3D’li Peşin/Taksitli Satış işlemlerinde istek gövdesi (body) içerisinde değerler açık bir şekilde değil, şifrelenmiş değer signedRequest alanında gönderilir.

signedRequest değeri, aşağıdaki tabloda yer alan alanlardan oluşturulan bir requestin şifrelenmesiyle elde edilir. Bu alanlardan zorunlu (Z) olarak işaretlenen herhangi biri eksik ya da hatalı gönderilirse işlem hata ile sonuçlanır.

signedRequest içerisine dahil edilecek alanlar ve kuralları aşağıdaki tablolarda belirtilmiştir. Kısaltmalar: (O) Opsiyonel, (Z) Zorunlu, (Ş) Şartlı.

Ana parametreler

Parametre Adı Format Uzunluk O/Z/Ş 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. OrderId alanı, alfanümerik karakterler ile yalnızca ‘-’ ve ‘’ karakterlerini içerebilir. Ancak, ‘-’ ve ‘’ karakterlerini art arda içermemelidir.
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 Ödemenin yapılacağı karta ait bilgileri (kart sahibi adı, kart numarası, son kullanma ayı/yılı ve CVV) içerir.
billingAddress Object O Fatura adresi bilgilerini içerir. Gönderilmesi durumunda işlem kaydında fatura adresi olarak saklanır.
shippingAddress Object O Teslimat adresi bilgilerini içerir. Fiziksel teslimat gerektiren siparişlerde gönderilmesi önerilir.
buyer Object Z Üye işyeri tarafındaki alıcıya ait bilgileri içerir.
basket Object O Siparişe ait sepet bilgilerini, yani satın alınan ürünlerin listesini ve detaylarını içerir.

card

Parametre Adı Format Uzunluk O/Z/Ş Açıklama
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

Parametre Adı Format Uzunluk O/Z/Ş Açıklama
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

Parametre Adı Format Uzunluk O/Z/Ş Açıklama
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

Parametre Adı Format Uzunluk O/Z/Ş Açıklama
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

Parametre Adı Format Uzunluk O/Z/Ş Açıklama
basketId String 50 Ş Üye işyeri tarafındaki sepete ait id. Basket içerisinde item iletilirse basketId gönderilmesi zorunlu olur.

basket/basketItems

Parametre Adı Format Uzunluk O/Z/Ş Açıklama
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.

İstek Token’ı Oluşturma (signedRequest)

İşlem güvenliği açısından, üye işyerleri tarafından iletilen isteklerdeki bilgilerin açık şekilde gönderilmesi tercih edilmez. Bunun yerine, istek gövdesi (body) içerisinde Tami tarafından istenen alanlara göre hazırlanan requestin imzalanıp şifrelenmesiyle oluşan signedRequest değerinin gönderilmesi beklenir.

SignedRequest oluşturma adımlarının ayrıntılı anlatımı ve kod örnekleri için İstek Token’ı Oluşturma (signedRequest) sayfasına bakabilirsiniz.

3D’li Satış İşlemi Başlatma API İstek Örneği

{\n \"signedRequest\": \"eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU4R0NNIiwiYWxnIjoiZGlyIn0..4MoTIhPxKWjzMcuawbuf.6rgfjy-PdfROZK_I5nBtpiVwaTDqAv6TQImDhUsFa-p6KMoK-DdYy1KdixUGgciyaRCuyCkTEoqu1bjRVHhbqMSW8Opm_EvAa5unwcdSfiZFLDs3NL7YmBDciTXAqSofNk4hcBUsqao2qg...\"\n}

Yukarıdaki signedRequest değeri örnek/test amaçlı kısaltılmıştır. Gerçek bir istek çok daha uzun bir JWE (şifrelenmiş token) değeri içerir.

3D’li Satış İşlemi Başlatma API İstek Cevabı Örneği

Başarılı işlemde dönen cevap:

{\n \"signedResponse\": \"eyJraWQiOiI0ODA0ZTU4MNU1OTBhWtqXxWmEpWkIjp7InQ1Y5Y5VgYjZ4YWcJiOiI2InZxIiwiYWxnIjoiZGly...\"\n}

3D’li Satış İşlemi Başlatma İstek Cevabı Parametreleri ve Açıklamaları

İşlem başarılı olduğunda, Tami tarafından iletilen cevap (response) içerisinde yalnızca signedResponse alanı döner. Aşağıdaki tabloda listelenen diğer tüm alanlar (success, systemTime, correlationId, orderId, amount, kart bilgileri, threeDSHtmlContent vb.) bu durumda response içerisinde açık olarak yer almaz; bunların tamamı signedResponse alanının içinde şifrelenmiş halde taşınır. Bu alanlara ancak signedResponse değeri çözümlendiğinde (decode edildiğinde) ulaşabilirsiniz.

İşlem başarısız olduğunda ise signedResponse hiç dönmez; bu durumda success, systemTime, correlationId, errorCode, errorMessage ve errorGroup alanları doğrudan açık olarak iletilir.

Parametre Adı Format Nerede Yer Alır Açıklama
success String signedResponse içinde (başarısız işlemde açık) 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 signedResponse içinde (başarısız işlemde açık) Tami tarafından yanıtın oluşturulduğu tarih ve saat bilgisini belirtir.
correlationId String signedResponse içinde (başarısız işlemde açık) İşlem numarası
transactionDate dateTime signedResponse içinde İşlemin gerçekleştirildiği tarih ve saat bilgisini belirtir.
orderId String signedResponse içinde Sipariş numarası
amount Number signedResponse içinde İşlem tutarı
currency String signedResponse içinde İşlem para birimi
installmentCount Number signedResponse içinde İşlem taksit sayısı
card/binNumber String signedResponse içinde Kartın ilk 8 hanesi
card/maskedNumber String signedResponse içinde Maskeli kart numarası
card/cardBrand String signedResponse içinde Kart markası
card/cardOrganization String signedResponse içinde Kart organizasyonu
card/cardType String signedResponse içinde Kart tipi
threeDSHtmlContent String signedResponse içinde 3D doğrulama sayfasına yönlendirecek HTML içeriğidir. İçerik Base64'te decode edilerek HTML elde edilir.
errorCode String Açık (yalnızca success:false durumunda) Hata kodu
errorMessage String Açık (yalnızca success:false durumunda) Hata mesajı
errorGroup String Açık (yalnızca success:false durumunda) İlgili hatanın grubunu gösterir. İşyerleri hata kodu ve hata gruplarından faydalanarak kendi tarafındaki kuralları yönetebilir.

3D Doğrulama

3D’li satış işlemini başlatma adımının sonucunda elde ettiğiniz HTML içerik üzerinden, kart sahibine kartının bankasına ait 3D doğrulama ekranı gösterilir. Kart sahibi cep telefonuna gelen şifreyi girdikten sonra, doğrulama sonucu Tami tarafından callbackUrl parametresinde belirttiğiniz adrese POST edilir.

3D doğrulamanın başarılı olması, henüz karttan bir tutarın tahsil edildiği anlamına gelmez. Cevapta dönen success alanı true olduğunda, işlemi satışa çevirmek için bir sonraki adım olan 3D’li satış işlemi tamamlama servisini çağırmanız gerekir.

İşlem güvenliğinin sağlanması amacıyla, Tami bu callback yanıtına bir hashedData değeri ekler. Bu değeri, aşağıdaki “HashedData Hesaplaması” başlığında anlatılan yöntemle kendi tarafınızda yeniden hesaplamanız ve Tami’nin ilettiği değerle karşılaştırmanız gerekir.

Hesapladığınız değer ile Tami’nin ilettiği hashedData değeri eşleştiğinde, ilgili yanıtın güvenli ve doğru kaynaktan geldiği teyit edilmiş olur ve 3D tamamlama adımına geçebilirsiniz. Bu doğrulamanın yapılması ve işlem güvenliğinin teyit edilmesi, üye işyerinin sorumluluğundadır.

Doğrulama cevabında dönen mdStatus değerinin 2, 3 veya 4 olması durumunda, işlem bankadan yarı güvenli (half secure) olarak doğrulanmıştır. Bu işlemler için 3D tamamlama adımına geçilip geçilmeyeceğine karar vermek üye işyerinin sorumluluğundadır; üye işyeri işleme devam etmek isterse tamamlama isteğini gönderebilir.

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
hashParams String hashedData değerini oluşturan parametrelerin bilgisini ve sırasını iletir. hashedData hesaplanırken bu alanda belirtilen sıra kullanılmalıdır.
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, yarı güvenli (half secure) durumlar için 2, 3 veya 4, başarısız durumlar için ise 0, 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ı

mdStatus değerleri

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

mdStatus Açıklama
mdStatus = 0 3-D Secure imzası geçersiz veya doğrulama hatalı
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

3D Doğrulama Cevabını Doğrulama (hashedData) 

3D doğrulama sonrası callbackUrl değerine dönen cevapta hashedData ve hashParams alanları bulunur. Cevabın gerçekten Tami’den geldiğinden ve yolda değişmediğinden emin olmak için bu hash’i doğrulamanız gerekir.

Kısaca süreç şöyle işler: Cevapta dönen hashParams değeri + karakterine göre ayrıştırılarak alan adları elde edilir. Ardından her alan adının cevaptaki karşılık gelen değeri, hashParams’taki sırayla uç uca birleştirilerek hashItems metni oluşturulur (alan adları değil, değerleri birleştirilir; boş değerler yerine boş string kullanılır). Son olarak bu metin, terminal secretKey değeri ile HMAC-SHA256 algoritmasından geçirilip Base64 kodlanır ve çıkan değer, cevaptaki hashedData ile karşılaştırılır. Değerler eşleşiyorsa cevap bütünlüğü doğrulanmış demektir; eşleşmiyorsa işlem incelenmelidir.

Not: Peşin işlemlerde installmentCount bilgisinin 1 olarak gönderilmesi beklenir. Bu bilgi de hashParams içinde yer alıyorsa hashItems’a eklenir.

Alan sıralamasının sabit olmaması sayesinde, Tami ileride hashParams içeriğine yeni bir alan ekler veya çıkarırsa, hesaplama mantığınızı değiştirmeniz gerekmez; her zaman cevapta dönen hashParams alanındaki sıralamayı esas almanız yeterlidir.

Doğrulama aşağıdaki 3 adımda yapılır:

1. hashParams’ı ayrıştırma

Cevapta dönen hashParams değeri + karakterine göre ayrıştırılır. Örnek bir hashParams değeri:

cardOrganization+cardBrand+cardType+maskedNumber+installmentCount+currencyCode+txnAmount+orderId+callbackUrl+systemTime+success

2. Değerleri sırayla birleştirme

Ayrıştırılan her alan adının, cevaptaki karşılık gelen değeri aynı sırayla uç uca eklenir (değer yoksa boş string kullanılır).

public static String buildHashItems(Map<String, String> responseMap) {\n String hashParams = responseMap.get(\"hashParams\");\n StringBuilder builder = new StringBuilder();\n for (String param : hashParams.split(\"\\\\+\")) {\n String value = responseMap.get(param); // alan ADI değil, DEĞERİ eklenir\n builder.append(value != null ? value : \"\");\n }\n return builder.toString();\n}

3. Hash’in hesaplanması ve karşılaştırılması

Elde edilen metin, terminal secretKey değeri ile HMAC-SHA256'dan geçirilir ve sonuç Base64 ile kodlanır. Çıkan değer, cevaptaki hashedData ile eşleşmelidir:

beklenenHash = Base64( HmacSHA256(hashItems, secretKey) )

Eşleşiyorsa cevap bütünlüğü doğrulanmıştır, işleme devam edilebilir. Eşleşmiyorsa cevap işleme alınmamalı ve destek ekibiyle iletişime geçilmelidir.

3D’li Satış İşlemi Tamamlama Hakkında

3D doğrulaması başarıyla tamamlanmış bir işlemi satışa çevirmek için bu servisi çağırmanız gerekir. Bu servis çağırılmadan işlem tamamlanmazsa, karttan ücret tahsil edilmemiş olur.

3D’li Satış İşlemi Tamamlama API Bilgileri

3D’li satış işlemini tamamlamak için kullanılacak endpoint bilgileri aşağıdadır:

Ortam Endpoint
Test (Sandbox) https://sandbox-paymentapi.tami.com.tr/api/v0/payment/complete-3ds
Üretim (Prod) https://paymentapi.tami.com.tr/api/v0/payment/complete-3ds

İsteklerinizi POST metodu ile, çalıştığınız ortama (test/üretim) uygun endpoint’e göndermeniz gerekir.

3D’li Satış İşlemi Tamamlama İsteğinin Atılma Yöntemi

3D’li satış işlemini tamamlarken de, gönderilen isteğin gövdesinde (body) değerler açık bir şekilde değil, imzalanarak şifrelenmiş tek bir değerin iletilmesi beklenir. Bu değer, signedRequest alanı ile gönderilir.

Tami tarafından dönen response da aynı şekilde imzalanarak şifrelenmiş olup signedResponse alanı içerisinde iletilir.

Bunlara ek olarak, header alanında da aşağıdaki bilgilerin gönderilmesi gerekir:

  • PG-Auth-Token: Nasıl hesaplanacağı yukarıdaki “PG Auth Token Oluşturma” başlığında anlatılmıştır.
  • CorrelationId: Her istek için tekil (unique) olması gereken, değişken bir değerdir.
  • PG-Api-Version: v4 olarak iletilmesi gerekir.

3D’li Satış İşlemi Tamamlama İmzalanarak Şifrelenecek Parametreler ve Açıklamaları

3D’li satış işlemini tamamlarken istek gövdesi (body) içerisinde değerler açık bir şekilde değil, şifrelenmiş değer signedRequest alanında gönderilir.

signedRequest değeri, aşağıdaki tabloda yer alan alandan oluşturulan bir requestin şifrelenmesiyle elde edilir. Zorunlu (Z) olarak işaretlenen alan eksik ya da hatalı gönderilirse işlem hata ile sonuçlanır. Kısaltmalar: (O) Opsiyonel, (Z) Zorunlu.

Alan Format Uzunluk O/Z Açıklama
orderId String (2-36) Z 3D doğrulaması başarıyla tamamlanmış sipariş numarası bilgisidir.

3D’li Satış İşlemi Tamamlama API İstek Örneği

{\n \"signedRequest\": \"eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU4R0NNIiwiYWxnIjoiZGlyIn0..8NpUJiQyLXlzObuawbuf.4sheky-SegUQK_L8pDwukZybVFsBw8VRLoFjWwJc-t9NQqN-FfBb4MejzLgjekBuyEmVFqw3aMcSXgqitbrPAZX9GyBs5voxeeTkjBHOFt6QN9bOCGhA-ZejufHzj3RF0IcjPt5MVWroPq7jdFXuvcr6...\"\n}

Yukarıdaki signedRequest değeri örnek/test amaçlı kısaltılmıştır. Gerçek bir istek çok daha uzun bir JWE (şifrelenmiş token) değeri içerir.

3D’li Satış İşlemi Tamamlama API İstek Cevabı Örneği

Başarılı işlemde dönen cevap:

{\n \"signedResponse\": \"eyJraWQiOiI1OTA1ZTY5MNY2MDFiWurYyWnFqWlIjp7InU1YTY1VhYjZ5YWdJiOiI3InZyIiwiYWxnIjoiZGly...\"\n}

3D’li Satış İşlemi Tamamlama İstek Cevabı Parametreleri ve Açıklamaları

İşlem başarılı olduğunda, Tami tarafından iletilen cevap (response) içerisinde yalnızca signedResponse alanı döner. Aşağıdaki tabloda listelenen diğer tüm alanlar (success, systemTime, correlationId, orderId, amount, kart bilgileri vb.) bu durumda response içerisinde açık olarak yer almaz; bunların tamamı signedResponse alanının içinde şifrelenmiş halde taşınır. Bu alanlara ancak signedResponse değeri çözümlendiğinde (decode edildiğinde) ulaşabilirsiniz.

İşlem başarısız olduğunda ise signedResponse hiç dönmez; bu durumda success, systemTime, correlationId, errorCode, errorMessage ve errorGroup alanları doğrudan açık olarak iletilir.

Parametre Adı Format Nerede Yer Alır Açıklama
success String signedResponse içinde (başarısız işlemde açık) True dönmesi durumunda satış başarılı, false dönmesi durumunda hata alınmıştır. Hata detayı errorCode ve errorMessage alanlarında paylaşılır.
systemTime dateTime signedResponse içinde (başarısız işlemde açık) Tami tarafından yanıtın oluşturulduğu tarih ve saat bilgisini belirtir.
correlationId String signedResponse içinde (başarısız işlemde açık) İşlem numarası
transactionDate dateTime signedResponse içinde İşlemin gerçekleştirildiği tarih ve saat bilgisini belirtir.
orderId String signedResponse içinde Sipariş numarası
amount Number signedResponse içinde İşlem tutarı
currency String signedResponse içinde İşlem para birimi
installmentCount Number signedResponse içinde İşlem taksit sayısı
card/binNumber String signedResponse içinde Kartın ilk 8 hanesi
card/maskedNumber String signedResponse içinde Maskeli kart numarası
card/cardBrand String signedResponse içinde Kart markası
card/cardOrganization String signedResponse içinde Kart organizasyonu
card/cardType String signedResponse içinde Kart tipi
errorCode String Açık (yalnızca success:false durumunda) Hata kodu
errorMessage String Açık (yalnızca success:false durumunda) Hata mesajı
bankAuthCode String signedResponse içinde Banka onay kodu
bankReferenceNumber String signedResponse içinde İşleme ait Retref numarası
errorGroup String Açık (yalnızca success:false durumunda) İlgili hatanın grubunu gösterir. İşyerleri hata kodu ve hata gruplarından faydalanarak kendi tarafındaki kuralları yönetebilir.

Cevap Token’ı Çözümleme (signedResponse)

signedResponse alanı içerisinde iletilen değerin çözümlenerek yukarıdaki parametrelere erişilmesi için gereken adımlar bu bölümde yer alacaktır.

Çözümleme adımlarının ayrıntılı anlatımı ve kod örnekleri için Cevap Token’ı Çözümleme (signedResponse) sayfasına bakabilirsiniz.

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

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özlemleyebilirsin. Bu sayede tercih ettiğiniz programlama diline dair daha iyi anlaşılır ve özgün örneklerle çalışma imkanı bulabilirsin.

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

Hata Kodları

Hata kodları listesine bu sayfadan ulaşabilirsin.

Test Kartları

Test kartları listesine bu sayfadan ulaşabilirsin.

Sıkça Sorulan Sorular

Key Value
CorrelationId Correlation{{randomNumber}}
PG-Auth-Token {{merchantNumber}}:{{terminalNumber}}:{{hash}}
PG-Api-Version v4
Headers kısmında correlationId ve PG-Auth-Token parametrelerinin iletilmesi beklenir. correlationId her işlem için string unique bir değer iletilmelidir. PG-Auth-Token parametresi de tabloda belirtildiği gibi işyerine ait merchantNumber, terminalNumber ve hash bilgilerinden oluşur. Hash bilgisi için de işyerine ait merchantNumber, terminalNumber ve secretKey bilgileri sha256 ile hashleyip stringe çevrilerek elde edilir.
Response
{
    "errorCode": 4003,
    "errorMessage": "Headerda gönderilen hash değeri tutarsız",
    "success": false ,
    "systemTime": "2024-05-07T13:22:49.941660017",
    "correlationId": "correlation94003a3b-5efc-4f34-b0f3-0ee531ebeb6e"
}
Satış, İptal/İade, Ön Otorizasyon, Ön Otorizasyon kapama, 3D'li satış ve 3D'li satış tamamlama isteklerinin tümünde header'da "PG-Auth-Token" parametresi iletilmeli.
Bu bilgi üye işyerine ait "merchantNumber:TerminalNumber:Hash" bilgilerinden oluşmaktadır. Hash bilgisinin istenen değerlere göre hesaplanarak PG-Auth-Token parametresine eklenmesi beklenir.
Satış >> Satış İşlemi Satış >> Ön Otorizasyon

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

Soru Sor Soru Sor
Kişisel Verilerin Korunması Çerez Politikası