-
Tami Sanal POS
Tami Sanal POS
3D'li Ön Otorizasyon İşlemi Genel Açıklama
3D’li ön otorizasyon işlemi, Tami üzerinden gerçekleştirmek istediğiniz bir ödeme için, 3D Secure doğrulamasıyla birlikte belirttiğiniz tutar kadar bakiyenin karttan bloke edilmesini sağlar.
İşlem iki adımdan oluşur: önce 3D’li ön otorizasyon işlemini başlatırsınız; bu adımın sonucunda dönen 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 doğrulama kodunu girdikten sonra 3D doğrulama sonucu belirlenir.
Doğrulama başarılı olursa, ödeme işlemini tamamlamak için 3D’li ön otorizasyon işlemini tamamlama servisini çağırmanız gerekir. Bloke edilen tutarı tahsil etmek için ise, bloke süresi içinde “Ön Otorizasyon Kapama” 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 {
public static String sha256(Long merchantNumber, Long terminalNumber, String secretKey) {
String text = merchantNumber.toString() + terminalNumber.toString() + secretKey;
try {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hash = digest.digest(text.getBytes(StandardCharsets.UTF_8));
String sha256Hex = DatatypeConverter.printBase64Binary(hash);
return sha256Hex;
} catch (NoSuchAlgorithmException e) {
e.printStackTrace();
return null;
}
}
}
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 Ön Otorizasyon İşlemi Başlatma Hakkında
3D’li bir ön otorizasyon 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 Ön Otorizasyon İşlemi Başlatma API Bilgileri
3D’li ön otorizasyon 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/pre-auth |
| Üretim (Prod) | https://paymentapi.tami.com.tr/api/v0/payment/pre-auth |
İsteklerinizi POST metodu ile, çalıştığınız ortama (test/üretim) uygun endpoint’e göndermeniz gerekir.
3D’li Ön Otorizasyon İşlemi Başlatma İsteğinin Atılma Yöntemi
3D’li ön otorizasyon 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 Ön Otorizasyon İşlemi Başlatma İmzalanarak Şifrelenecek Parametreler ve Açıklamaları
3D’li ön otorizasyon 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
Tip: List (O)
| 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 Ön Otorizasyon İşlemi Başlatma API İstek Örneği
{
"signedRequest": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU4R0NNIiwiYWxnIjoiZGlyIn0..2GrWLiRzNXkASeuawbuf.0vhgnz-ViiYSL_M9sFuzocajEt9WUOrGlZzJd-u0OQrQ-IiDd7PfkzOjfoDzh4QL0PiieZmHbpZ1wur5wuETbA10JzFv7wptgjxTmoZLs7RP0JdkQrVqtxRqzcmh4ifHBuxfd9..."
}
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 Ön Otorizasyon İşlemi Başlatma API İstek Cevabı Örneği
Başarılı işlemde dönen cevap:
{
"signedResponse": "eyJraWQiOiI3MTI3ZTg3MPc4MjNkWvsZzXoGsWnIjp7Inc2YzY3VmYjZ7YWVKiOiI5InZ0IiwiYWxnIjoiZGly..."
}
3D’li Ön Otorizasyon İş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 işlem 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 ön otorizasyon 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 bloke edildiği anlamına gelmez. Cevapta dönen success alanı true olduğunda, bakiyeyi bloke etmek için bir sonraki adım olan 3D’li ön otorizasyon işlemi tamamlama servisini çağırmanız gerekir. Bu adım tamamlanmadığı sürece karttan herhangi bir bloke işlemi gerçekleşmez.
İş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ğudur; üye işyeri işleme devam etmek isterse tamamlama isteğini gönderebilir.
Not: Bu adım, Tami API’sine giden bir istek değil, bankadan üye işyerinize gelen bir bildirimdir. Bu nedenle signedRequest / signedResponse ve PG-Auth-Token mekanizmasının dışında kalır; aşağıdaki parametreler ve hashedData hesaplaması değişmeden kalıyor.
3D Doğrulama Cevabı Parametreleri ve Açıklamaları
Cevap parametreleri
| 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) {
String hashParams = responseMap.get("hashParams");
StringBuilder builder = new StringBuilder();
for (String param : hashParams.split("\\+")) {
String value = responseMap.get(param); // alan ADI değil, DEĞERİ eklenir
builder.append(value != null ? value : "");
}
return builder.toString();
}
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 Ön Otorizasyon İşlemi Tamamlama Hakkında
3D doğrulaması başarıyla tamamlanmış bir işlemde bakiyeyi bloke etmek için bu servisi çağırmanız gerekir. Bu servis çağırılmadan işlem tamamlanmazsa, karttan herhangi bir tutar bloke edilmemiş olur.
Bakiye bloke edildikten sonra, tahsilat için “Ön Otorizasyon Kapama” servisini çağırmanız gerekir.
3D’li Ön Otorizasyon İşlemi Tamamlama API Bilgileri
3D’li ön otorizasyon 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 Ön Otorizasyon İşlemi Tamamlama İsteğinin Atılma Yöntemi
3D’li ön otorizasyon 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 Ön Otorizasyon İşlemi Tamamlama İmzalanarak Şifrelenecek Parametreler ve Açıklamaları
3D’li ön otorizasyon 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 Ön Otorizasyon İşlemi Tamamlama API İstek Örneği
{
"signedRequest": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU4R0NNIiwiYWxnIjoiZGlyIn0..5KtYNjSAPZmCUfuawbuf.3wjikb-XkkASN_O1tGzwpkbzcWGuCx0XTNrHlZxLf-w2SRsR-JjFd9SgkALijfpEyi5Sn7baPG0mb2vtkgzbddMkiZj5xrpygkxWoqbTt9SekLctTsxSs0jrngIaxif..."
}
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 Ön Otorizasyon İşlemi Tamamlama API İstek Cevabı Örneği
Başarılı işlemde dönen cevap:
{
"signedResponse": "eyJraWQiOiI4MjM4ZTk4MQd4OTM0ZXt0a1l0WoGoWmIjp7InQ3Y3Y3VnYjZ4YWVKiOiIwInZ0IiwiYWxnIjoiZGly..."
}
3D’li Ön Otorizasyon İş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 işlem 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. Bu adımlar, yukarıdaki “Başlatma” adımı için anlatılan signedResponse çözümleme mantığıyla aynıdı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.
- 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.
- NodeJS 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 gerekebilir.
Hata Kodları
Hata kodları listesine bu sayfadan ulaşabilirsin.
Test Kartları
Test kartları listesine bu sayfadan ulaşabilirsin.
