-
Tami Sanal POS
Tami Sanal POS
İşlem Sorgulama İşlemi Genel Açıklama
İşlem sorgulama servisi, Tami üzerinden gerçekleştirilen işlemlerin güncel durumunu ve komisyon bilgilerini sorgulamanıza imkân tanır. Belirli bir sipariş numarası özelinde veya belirli bir tarih aralığında gerçekleşen tüm işlemler bu servis üzerinden sorgulanabilir.
Sorgulama sonucunda, ilgili siparişin güncel durumu ile bu sipariş kapsamında gerçekleştirilen tüm işlemlere (satış, iptal, iade vb.) ait detaylı bilgiler iletilir. Siparişin yalnızca güncel durumunun görüntülenmesi istenirse, isTransactionDetail alanının false olarak gönderilmesi yeterlidir.
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.
Sorgulama İşlemi API Bilgileri
İşlem sorgulama için kullanılacak endpoint bilgileri aşağıdadır:
| Ortam | Endpoint |
|---|---|
| Test (Sandbox) | https://sandbox-paymentapi.tami.com.tr/api/v0/payment/orderQuery |
| Üretim (Prod) | https://paymentapi.tami.com.tr/api/v0/payment/orderQuery |
İsteklerinizi POST metodu ile, çalıştığınız ortama (test/üretim) uygun endpoint’e göndermeniz gerekir.
Sorgulama İsteğinin Atılma Yöntemi
İşlem sorgulama isteklerinde 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. signedResponse değerinin nasıl çözümleneceğine dair detaylı bilgi aşağıdaki başlıklarda yer almaktadır.
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.
İmzalanarak Şifrelenecek Parametreler ve Açıklamaları
İşlem sorgulama isteğinde 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.
signedRequest içerisine dahil edilecek alanlar ve kuralları aşağıdaki tabloda belirtilmiştir. Kısaltmalar: (O) Opsiyonel, (Z) Zorunlu, (Ş) Şartlı.
| Alan | Format | O/Z/Ş | Açıklama |
|---|---|---|---|
| orderId | String | Ş | Sorgulanmak istenen satış işlemine ait sipariş numarası bilgisidir. startDate ve endDate alanları gönderilmezse bu alanın gönderilmesi zorunludur. |
| isTransactionDetail | Boolean | O | true gönderilirse siparişin başından geçen tüm işlemler paylaşılır. false, boş ya da hiç gönderilmezse siparişin sadece son durumuna ait bilgiler iletilir. |
| startDate | String | Ş | Sipariş numarasına göre değil, tarih aralığına göre sorgulama yapılmak istenirse bu alan zorunludur. Örnek format: "DD-MM-YYYY HH:MM:SS". Başlangıç ve bitiş tarihi arasında en fazla 30 günlük bir aralık verilebilir. |
| endDate | String | Ş | Sipariş numarasına göre değil, tarih aralığına göre sorgulama yapılmak istenirse bu alan zorunludur. Örnek format: "DD-MM-YYYY HH:MM:SS". |
| page | Integer | O | Sorgulanan tarih aralığındaki işlemler sayfa sayfa çekilmek istenirse gönderilir. İlk sayfa için 0 gönderilmelidir. |
| size | Integer | O | Sayfalandırma yapıldığında bir sayfada gösterilecek işlem sayısını belirtir. |
| sortField | String | O | Sorgulama sonucunun belirli bir alana göre sıralı gelmesini sağlar. Örnek: "orderDate". |
| sortDirection | Enum | O | Sıralamanın artan ya da azalan olmasını belirler. Alabileceği değerler: ASC, DESC. |
İ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.
API İstek Örneği
{
"signedRequest": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU4R0NNIiwiYWxnIjoiZGlyIn0..7NrZMmVDSawFXiuawbuf.3zkmpc-anpDVQ_R4wJbzqmecZJxEz1YZQuoiezoOi-z5VvU-MmFi1RhlDOmgrqGBi6Ts0ncbSK3pldAzxGWcgE41LbHw9rqxjjcXppdDyU2MtrsaY1yltpdcuugDClki..."
}
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. Şifreleme öncesi (plain) gövdenin neye benzediğini görmek isterseniz, şifrelenecek alanlar yukarıdaki “İmzalanarak Şifrelenecek Parametreler” tablosunda listelenmiştir.
API İstek Cevabı Örneği
Başarılı işlemde dönen cevap:
{
"signedResponse": "eyJraWQiOiI2NzA2ZTkwNSe5MDY0ZXl1YmxxbmNqWoUoWpJjp7InM1Y5Y5VpYjZ7YWVNiOiIzInZ2IiwiYWxnIjoiZGly..."
}
İ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, content, pageInfo 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. Çözümleme adımları bir sonraki başlıkta anlatılmaktadır.
İşlem başarısız olduğunda ise signedResponse hiç dönmez; bu durumda success, systemTime, correlationId, errorCode ve errorMessage alanları doğrudan açık olarak iletilir.
Ana alanlar
| Parametre Adı | Format | Nerede Yer Alır | Açıklama |
|---|---|---|---|
| success | String | signedResponse içinde (başarısız işlemde açık) | Sorgulama isteğinin sonucudur. true olması durumunda sorgulanan işleme ait veriler döner. |
| 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) | Üye işyeri tarafından sorgulama isteğinde iletilen işlem numarasıdır. |
| errorCode | String | Açık (yalnızca success:false durumunda) | success alanı false olması durumunda cevapta yer alır; alınan hatanın kodudur. |
| errorMessage | String | Açık (yalnızca success:false durumunda) | success alanı false olması durumunda cevapta yer alır; alınan hatanın açıklamasıdır. |
| content | List | signedResponse içinde | Sorgulanan işlem(ler)e ait detayların listesidir. Her eleman, tek bir siparişe ait sonucu temsil eder. |
| pageInfo | Object | signedResponse içinde | Dönen cevaptaki işlemlerin sayfalandırılmasıyla ilgili bilgileri içerir. |
content
| Parametre Adı | Format | Nerede Yer Alır | Açıklama |
|---|---|---|---|
| content/orderId | String | signedResponse içinde | Sorgulanan siparişin numarasıdır. |
| content/amount | Number | signedResponse içinde | İşlemin güncel, işlem yapılabilir tutar bilgisidir. Örneğin 100 TL’lik bir satış işlemi sonrası 20 TL’lik bir iade yapıldıysa bu alan 80 TL görünür. |
| content/orderDate | DateTime | signedResponse içinde | Siparişin oluşturulma tarihidir. |
| content/currency | String | signedResponse içinde | İşlemin döviz kodudur. |
| content/installmentCount | Number | signedResponse içinde | İşlemin taksit sayısıdır. |
| content/orderStatus | String | signedResponse içinde | Siparişin son işlem tipini gösterir. AUTH, REVERSE, REFUND, PARTIAL_REFUND, PRE_AUTH, POST_AUTH, CHARGEBACK değerlerini alabilir. |
| content/paymentStatus | String | signedResponse içinde | İşlemin son durumunu gösterir. NOT_COMPLETED, SUCCESS, FAIL, TIME_OUT değerlerini alabilir. |
| content/commissionRate | BigDecimal | signedResponse içinde | İşleme ait komisyon oranı bilgisidir. |
| content/commissionAmount | BigDecimal | signedResponse içinde | İşleme ait hesaplanmış komisyon tutarını ifade eder. |
| content/transactionFee | BigDecimal | signedResponse içinde | İşlem ücreti bilgisidir. |
| content/holdPeriod | Integer | signedResponse içinde | İşlemin bloke gün sayısını ifade eder. |
| content/card | Object | signedResponse içinde | İşlemde kullanılan karta ait bilgileri içerir. |
| content/transactions | List | signedResponse içinde | isTransactionDetail: true gönderilirse, ilgili sipariş üzerinde yapılan tüm işlemlerin verisi bu alanda döner. |
content/card
| Parametre Adı | Format | Nerede Yer Alır | Açıklama |
|---|---|---|---|
| content/card/binNumber | String | signedResponse içinde | İşlemde kullanılan kartın ilk 8 hanesi. |
| content/card/cardBrand | String | signedResponse içinde | İşlemde kullanılan kartın bankasını ifade eder. |
| content/card/cardOrganization | String | signedResponse içinde | Kart organizasyon bilgisidir. AMEX, TROY, MASTERCARD, VISA vb. |
| content/card/cardType | String | signedResponse içinde | Kart tipidir. CREDIT, DEBIT |
content/transactions
| Parametre Adı | Format | Nerede Yer Alır | Açıklama |
|---|---|---|---|
| content/transactions/amount | Number | signedResponse içinde | İlgili işlemin tutarını ifade eder. |
| content/transactions/transactionType | String | signedResponse içinde | İlgili kaydın işlem tipidir. |
| content/transactions/transactionStatus | String | signedResponse içinde | İlgili kaydın başarı durumudur. |
| content/transactions/transactionDate | DateTime | signedResponse içinde | İlgili kaydın gerçekleştiği tarihtir. |
| content/transactions/reason | String | signedResponse içinde | İşlem iade/iptal edilirken bir reason alanı gönderilmişse, sorgulamada da bu alan döner. |
| content/transactions/bankAuthCode | String | signedResponse içinde | Banka onay kodu. |
| content/transactions/bankReferenceNumber | String | signedResponse içinde | İşleme ait Retref numarası. |
| content/transactions/fraudStatus | Boolean | signedResponse içinde | Fraud kontrolleri sonrasındaki durumu belirtir. |
pageInfo
| Parametre Adı | Format | Nerede Yer Alır | Açıklama |
|---|---|---|---|
| pageInfo/page | Integer | signedResponse içinde | Sorgulanan datanın döndüğü sayfa numarasını ifade eder. |
| pageInfo/size | Integer | signedResponse içinde | Dönen cevaptaki sayfada yer alan işlem adedini belirtir. |
| pageInfo/totalElements | Integer | signedResponse içinde | İstekte sayfa sayfa dönüş istendiyse, sorgulanan tarih aralığındaki toplam işlem adedini ifade eder. Her farklı sipariş numarası 1 işlem sayılır; bir işleme ait iptal/iade gibi alt işlemler bu sayıya dahil edilmez. |
| pageInfo/totalPages | Integer | signedResponse içinde | İstekte sayfa sayfa dönüş istendiyse, girilen size değerine göre, sorgulanan tarih aralığında toplam kaç sayfa olduğunu ifade eder. |
| pageInfo/isFirst | Boolean | signedResponse içinde | Dönen sayfa ilk sayfaysa true olarak gösterilir. |
| pageInfo/isLast | Boolean | signedResponse içinde | Dönen sayfa son sayfaysa true olarak gösterilir. |
| pageInfo/hasNext | Boolean | signedResponse içinde | Bir sonraki sayfa mevcutsa true olarak gösterilir. |
| pageInfo/hasPrevious | Boolean | signedResponse içinde | Önceki bir sayfa mevcutsa true olarak gösterilir. |
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.
- 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.
