Tosla İşim Geliştirici Merkezi

Ortam Bilgileri

Test Ortam URL https://prepentegrasyon.tosla.com/swagger

ClientId 1000000494

ApiUser POS_ENT_Test_001

ApiPass POS_ENT_Test_001!*!*

Production (Üretim) Ortam URL https://entegrasyon.tosla.com/api/Payment/

* Production (Üretim) ortamı için clientId, apiUser, apiPass bilgileriniz entegrasyonunuz tamamlandıktan sonra iletilecektir.

Zorunlu Parametreler

Tüm API çağrılarında aşağıdaki parametrelerin gönderilmesi gerekmektedir.

Hash Üretimi

• ApiPass, ClientId, ApiUser, RandomString, TimeSpan değerleri sırasıyla uc uca eklenerek string oluşturulur.
• Oluşturulan string'in SHA512 algoritması ile Byte hash'i alınır.
• Oluşturulan byte hash base64 encode edilerek hash değeri oluşturulur.

.Net Örnek Hash Fonksiyonu

                            private string CreateHash()
                            {
                                var randomGenerator = new Random();
                                var ApiPass = "POS_ENT_Test_001!*!*";
                                var ClientId = "1000000494";
                                var ApiUser = "POS_ENT_Test_001";
                                var Rnd = randomGenerator.Next(1, 1000000).ToString();
                                var TimeSpan = DateTime.Now.ToString("yyyyMMddHHmmss");
                                var hashString =ApiPass + ClientId + ApiUser + Rnd + TimeSpan;
                                System.Security.Cryptography.SHA512 sha = new System.Security.Cryptography.SHA512CryptoServiceProvider();
                                byte[] bytes = Encoding.UTF8.GetBytes(hashString);
                                byte[] hashingbytes = sha.ComputeHash(bytes);
                                var hash = Convert.ToBase64String(hashingbytes);
                                return hash;
                            }
                        

PHP Örnek Hash Fonksiyonu

                            public function generateHash()
                            {
                                    $apiPass = "POS_ENT_Test_001!*!*";
                                    $clientId = "1000000494";
                                    $apiUser = "POS_ENT_Test_001";
                                    $rnd = rand(1, 10000);
                                    $timeSpan = time();
                            
                                    $hashString = $apiPass . $clientId . $apiUser . $rnd . $timeSpan;
                                    $hashingbytes = hash("sha512", ($hashString), true);
                                    $hash = base64_encode($hashingbytes);
                                    return $hash;
                            }
                        

CallBack URL Hash Doğrulama Mekanizması

• CallbackURL’e dönen HashParameters içinde yer alan parametrelerin başına apiPass eklenerek Hash generate edilerek Hash validasyonu yapılabilir.
  

.Net Örnek Hash Fonksiyonu

                            static void Main(string[]args)
                            {
                                //var hashString = apiPass + threeDsession.ClientId + threeDsession.ApiUser +;
                                threeDsession.OrderId + threeDsession.MdStatus + threeDsession.BankResponseCode + 
                                threeDsession.BankResponseMessage + threeDsession.RequestStatus;
                                var hashString = "DGSApi123.123" + "1000000061" + "DGS_Api" + "P-2" + "1" + "00"+
                                "Onaylandı" + "1";
                                var hash = CalculateHash(string inputData)
                                }
                                public static string CalculateHash(string inputData)
                                {
                                string hash = "";
                                System.Security.Cryptography.SHA512 sha = new
                                System.Security.Cryptography.SHA512CryptoServiceProvider(); byte[]
                                bytes = Encoding.UTF8.GetBytes(inputData);
                                byte[] hashingbytes = sha.ComputeHash(bytes);
                                hash = Convert.ToBase64String(hashingbytes);
                                return hash;
                            }
                      

Ödeme İşlem Başlatma

Ödeme formu ve Ortak Ödeme Sayfası ile ödeme işlemi başlatmak için ThreeDSessionId değeri üretilmelidir. Bu servis 3D secure başlatılması için session açar ve sessionId bilgisini döner.

Bu servisten dönen ThreeDSessionId değeri ödeme formunda veya ortak ödeme sayfa çağırma işleminde kullanılır.

ThreeDSessionId 3D doğrulama işleminde kullanılan benzersiz değerdir. Her başarılı/başarısız işlem için tekrar üretilmelidir.

Method Name : threeDPayment

Http Method : Post

Content-Type : application/json

Request Parametreleri

Response Parametreleri

Örnekler - Komisyon Yansıtılmasının Kullanılmadığı Durum

{
                            "clientId": 1,
    "apiUser": "testUser",
    "rnd": "***",
    "timeSpan": "20191121160000",
    "hash": "***",
    "orderId": "12345678901234567890",
    "callbackUrl": "***merchantCallbackUrl***",
    "description": "açıklama",
    "echo": "string",
    "extraParameters": "string",
    "amount": 100,
    "currency": 949,
    "installmentCount": 0
                           }

{
                             
    "Code": 0,
    "Message": "Başarılı",
    "ThreeDSessionId": "***",
    "TransactionId": "12345"
}

Örnekler - Komisyon Yansıtıldığı Durum

{
                            "clientId": 1,
    "apiUser": "testUser",
    "rnd": "***",
    "timeSpan": "20191121160000",
    "hash": "***",
    "orderId": "12345678901234567890",
    "callbackUrl": "***merchantCallbackUrl***",
    "description": "açıklama",
    "echo": "string",
    "extraParameters": "string",
    "isCommission ":1,
    "amount": 100,
    "totalAmount "102,
    "currency": 949,
    "installmentCount": 0
}

{
                             
   "Code": 0,
    "Message": "Başarılı",
    "ThreeDSessionId": "***",
    "TransactionId": "12345"
}

3D ile Ödeme

Kredi kartı bilgileri girildikten sonra kullanıcıyı 3D Ödeme akışına yönlendirir. İşlem sonucunu callbackUrl parametresinde belirttiğiniz adrese POST eder.

Kurallar & Uyarılar

• API entegrasyonunda üye işyeri kendi ödeme formunu kullanır.
• Form görsel tasarımını üye iş yeri istediği gibi tasarlayabilir.
• Kredi kartı numarası (PAN) luhn algoritmasına tabi tutularak kontrol edilmeli, doğruluğu teyit edildikten sonra API'ye gönderilmelidir.
• Kartın hamilinin adı ve soyadı alınmalıdır.
• Son kullanma tarihi geçmiş kartlar ile API'ye sorgu yapılmamalıdır.
• Ödeme formu American Express (AMEX) kartları ile işlem alabilir şekilde tasarlanmalıdır.
• Formunuzdaki input name değerleri aşağıdaki parametreler ile aynı olmalıdır.

Method Name : ProcessCardForm
Http Method : Post
Content-Type : multipart/form-data

Request Parametreleri

Response

'Ödeme İşlem Başlatma' adımındaki callbackUrl parametresinde belirttiğiniz adrese 3D işlem sonucunu POST eder.

3D İşlem Sonucu Response POST Parametreleri

Eğer BankResponseCode 00 ise ödeme işlem başarılıdır. Bunun dışındaki tüm işlemler başarısız olarak kabul edilir.

3D Otorizasyon (PreAuth - PostAuth)

Müşteriden tahsilat yapmadan önce kredi kartında otorizasyon yapmak için kullanılır.

Otorizasyon Adımları

1. ThreeDPreAuth servisi ile ön otorizasyon işlemi başlatılır. Servis ThreeDSessionId değeri döner. ThreeDPreAuth servisini inceleyiniz.
2. ThreeDSessionId değeri ile ProcessCardForm servisine kredi kartı bilgileri form POST edilerek otorizasyon alınır. Bu aşamada tutar, müşteri kredi kartından bloke edilir. Bu işlem için "3D ile Ödeme" adımını inceleyiniz.
3. Otorizasyon işleminin tamamlanıp tutarın tahsil edilmesi için postAuth servisi çağrılır. postAuth servisi çağrıldıktan sonra işlem finansallaşır ve tahsilat gerçekleşmiş olur. PostAuth servisini inceleyiniz.

Notlar

1. ThreeDPreAuth, ProcessCardForm ve PostAuth servisleri farklı zamanlarda çağrılabilir.
2. İstenilen bir zamanda "İptal" adımı takip edilerek. Otorizasyon işlemi iptal edilip, kart üzerindeki tutar blokesi kaldırılabilir.

ThreeDPreAuth

Müşteriden bir ön otorizasyon alma işlemi başlatır.

Method Name : threeDPreAuth
Http Method : Post
Content-Type : application/json

Request Parametreleri

Response Parametreleri

Örnekler

{
                          "clientId": 1,
                          "apiUser": "***",
                          "rnd": "***",
                          "timeSpan": "20191121160000",
                          "hash": "***",
                          "orderId": "12345678901234567890",
                          "callbackUrl": "***merchantCallbackUrl***",
                          "amount": 100,
                          "currency": 949,
                          "extraparameters": "abc"
                          }

{
                          "code": 0,
                          "message": "Başarılı",
                          "threeDSessionId": "***"
                          }

PostAuth

Müşteriden bir ön otorizasyon alma işlemi başlatır.

Method Name : postAuth
Http Method : Post
Content-Type : application/json

Request Parametreleri

Response Parametreleri

Örnekler

{
                                                  "clientId": 1,
                                                  "apiUser": "testUser",
                                                  "rnd": "***",
                                                  "timeSpan": "20191121160000",
                                                  "hash": "***",
                                                  "orderId": "12345678901234567890",
                                                  "amount": 2211,
                                                  "extraparameters": "abc"
                                                  }

{

  "code": 0,
  "message": "Başarılı",
  "orderId": "12345678901234567890"
}
                                                  "code": 0,
                                                  "message": "Başarılı",
                                                  "orderId": "12345678901234567890"
                                                  }

Non3D ile Ödeme

Kredi kartı bilgileri girildikten sonra kullanıcıyı Non3D Ödeme akışına yönlendirir. 3D ile ÖDEME adımında girilen Kurallar ve Uyarılar burada da geçerli olmalıdır.

Kurallar & Uyarılar

• API entegrasyonunda üye işyeri kendi ödeme formunu kullanır.
• Form görsel tasarımını üye iş yeri istediği gibi tasarlayabilir.
• Kredi kartı numarası (PAN) luhn algoritmasına tabi tutularak kontrol edilmeli, doğruluğu teyit edildikten sonra API'ye gönderilmelidir.
• Kartın hamilinin adı ve soyadı alınmalıdır.
• Son kullanma tarihi geçmiş kartlar ile API'ye sorgu yapılmamalıdır.
• Ödeme formu American Express (AMEX) kartları ile işlem alabilir şekilde tasarlanmalıdır.
• Formunuzdaki input name değerleri aşağıdaki parametreler ile aynı olmalıdır.

Method Name : Payment
Http Method : Post
Content-Type : application/json

Request Parametreleri

Response

Eğer BankResponseCode 00 ise işlem başarılıdır. Bunun dışındaki tüm işlemler başarısız olarak kabul edilir.

Örnekler - Komisyon Yansıtılmasının Kullanılmadığı Durum

{
                            "clientId": 1,
    "apiUser": "testUser",
    "rnd": "***",
    "timeSpan": "20191121160000",
    "hash": "***",
    "orderId": "12345678901234567890",
    "callbackUrl": "***merchantCallbackUrl***",
    "description": "açıklama",
    "echo": "string",
    "extraParameters": "string",
    "amount": 100,
    "currency": 949,
    "installmentCount": 0
                           }

{
                             
    "Code": 0,
    "Message": "Başarılı",
    "ThreeDSessionId": "***",
    "TransactionId": "12345"
}

Örnekler - Komisyon Yansıtıldığı Durum

{
                            "clientId": 1,
    "apiUser": "testUser",
    "rnd": "***",
    "timeSpan": "20191121160000",
    "hash": "***",
    "orderId": "12345678901234567890",
    "callbackUrl": "***merchantCallbackUrl***",
    "description": "açıklama",
    "echo": "string",
    "extraParameters": "string",
    "isCommission ":1,
    "amount": 100,
    "totalAmount "102,
    "currency": 949,
    "installmentCount": 0
}

{
                             
   "Code": 0,
    "Message": "Başarılı",
    "ThreeDSessionId": "***",
    "TransactionId": "12345"
}

Ortak Ödeme Sayfası

Kendi özel ödeme formunu kullanmak istemeyen üye işyerleri için uygundur. 'Ödeme İşlem Başlatma' adımında oluşturulan threeDSessionId değeri ile Ortak Ödeme Sayfası iframe içinde gösterilebilir ya da kullanıcı doğrudan bu linke yönlendirilebilir. Ödeme işlem sonucu CallbackUrl adresine sistem tarafından POST edilir.

Not: Kullanıcının bankanın 3D sayfasına yönlendirme yapılabilmesi için browser desteği gerekmektedir.

Method Name : threeDSecure
Http Method : get
Content-Type : html/text

Request Parametreleri

<iframe src="https://[Ortam URL]/api/Payment/threeDSecure/[threeDSessionId]" height="500" width="100%"></iframe>

Ortam URL bilgisinin "Üretim Ortamında" değiştirilmesi gerekmektedir. Link formatı [Ortam URL] /threeDSecure/ [threeDSessionId]'dır.

Taksit ve Komisyon Bilgisi

Bin numarasına göre kartın bağlı olduğu banka bilgileri ile birlikte sunulabilecek taksit ve komisyon oranlarını gönderir.

Method Name :GetCommissionAndInstallmentInfo
Http Method : Post
Content-Type : application/json

Request Parametreleri

Response Parametreleri

Örnekler

{
 "bin": 407814,
 "clientId": 1000000000,
 "apiUser": "XXXXXXXX",
 "rnd": "string",
 "timeSpan": "string",
 "hash": "XXXXXXXX"
 }

{
 "CardPrefix": 407814,
 "BankId": 9,
 "BankCode": "ZiraatBankası",
 "BankName": "Ziraat Bankası",
 "CardName": "Bankkart",
 "CardClass": "Banka Kartı",
 "CardType": "Visa",
 "Country": "TR",
 "BankCommission": 0,
 "InstallmentInfo": {
 "T2": {
 "Rate": 2.99,
 "Constant": 2
 },
 "T3": {
 "Rate": 3.99,
 "Constant": 2
 },
 "T4": {
 "Rate": 4.99,
 "Constant": 2
 },
 "T5": {
 "Rate": 5.99,
 "Constant": 2
 },
 "T6": {
 "Rate": 6.99,
 "Constant": 0
 },
 "T7": {
 "Rate": 7.99,
 "Constant": 0
 },
 "T8": {
 "Rate": 8.99,
 "Constant": 0
 },
 "T9": {
 "Rate": 9.99,
 "Constant": 0
 },
 "T10": {
 "Rate": 10.99,
 "Constant": 0
 },
 "T11": {
 "Rate": 11.99,
 "Constant": 0
 },
 "T12": {
 "Rate": 12.99,
 "Constant": 0
 }
 },
 "Code": 0,
 "Message": ""
 }

Taksit ve Taksitlere Karşılık Gelen Tutar Bilgisi

isCommission 1 gönderildiği durumda amount değerine karşılık gelen taksitlerdeki totalAmount değerinde gönderilecek değerler döner.

Method Name :GetInstallmentOptions
Http Method : Post
Content-Type : application/json

Request Parametreleri

Response Parametreleri

Örnekler

{
  "amount": 10000,
  "clientId": 1000000000,
  "apiUser": "XXXXXXXX",
  "rnd": "string",
  "timeSpan": "string",
  "hash": "XXXXXXXX"
}

{
  "installmentOptions": [
    {
      "installment": 1,
      "title": "Tek Çekim",
      "amount": 10000,
      "currency": 949
    },
    {
      "installment": 2,
      "title": "2 Taksit",
      "amount": 10089,
      "currency": 0
    }
    {
      "installment": 3,
      "title": "3 Taksit",
      "amount": 10115,
      "currency": 949
    }
   ],
  "Code": 0,
  "Message":""
 }

Ödeme Sorgulama

Tosla İşim de kaydı oluşturulan bir işlemin detayları sorgulanabilir. İşlem sorgulama servisidir. OrderID ile işlem sorgulama yapılabilmektedir.

Method Name : inquiry
Http Method : Post
Content-Type : application/json

Request Parametreleri

Response Parametreleri

Örnekler

{
 "clientId": 1,
 "apiUser": "***",
 "rnd": "***",
 "timeSpan": "20221011235931",
 "hash": "***",
 "orderId": "20221011999",
 "transactionId": ""
 } 

{
 "Count": 36,
 "Transactions": [
 {
 "TransactionType": 1,
 "CreateDate": "20221011152449",
 "OrderId": "20221011999",
 "BankResponseCode": "00",
 "BankResponseMessage": "Onaylandı",
 "AuthCode": "S90037",
 "HostReferenceNumber": "228415127919",
 "Amount": 1090,
 "Currency": 949,
 "InstallmentCount": 0,
 "ClientId": 1000000494,
 "CardNo": "41595600****7732",
 "RequestStatus": 1,
 "RefundedAmount": 0,
 "PostAuthedAmount": 0,
 "TransactionId": 2000000000029968,
 "CommissionStatus": 1,
 "NetAmount": 1090,
 "MerchantCommissionAmount": 0,
 "MerchantCommissionRate": 0,
 "CardBankId": 13,
 "CardTypeId": 2,
 "ValorDate": 0,
 "TransactionDate": 20221011,
 "BankValorDate": 0,
 "ExtraParameters": null,
 "Code": 0,
 "Message": "Başarılı"
 }
 ],
 "Code": 0,
 "Message": "Başarılı"
 }

İşlem Listeleme

Tarihe göre işlemleri listeler. Tarih gönderilerek iletilen tarihteki tüm işlemlerin listelenmesini sağlar.

Method Name : history
Http Method : Post
Content-Type : application/json

Request Parametreleri

Response Parametreleri

Örnekler

{
 "OrderId": " A1B2C3D4",
 "ClientId": 1,
 "ApiUser": "apiuser",
 "Rnd": "string",
 "TimeSpan": "20220119111007",
 "Hash": " A1B2C3D4",
 "Page": 1,
 "PageSize": 10,
 "TransactionDate": 20220412
 }
 

{
 "Code": 101,
 "Message": "string",
 "Count": 123,
 "Transactions": [
 {
 "TransactionType": 1,
 "CreateDate": "20220119111007",
 "OrderId": " A1B2C3D4",
 "BankResponseCode": "MD99",
 "BankResponseMessage": "mesaj",
 "AuthCode": null,
 "HostReferenceNumber": null,
 "Amount": 100,
 "Currency": 949,
 "InstallmentCount": 1,
 "ClientId": 1,
 "CardNo": "123456******1234",
 "RequestStatus": 0,
 "RefundedAmount": 0,
 "PostAuthedAmount": 0,
 "TransactionId": 0,
 "CommissionStatus": null,
 "NetAmount": 0,
 "MerchantCommissionAmount": 0,
 "MerchantCommissionRate": null,
 "CardBankId": 0,
 "CardTypeId": 0,
 "Code": 0,
 "Message": ""
 }
 ]
 }

İptal

Bankalar gün sonu almadan önce işlemin iptal edilmesidir. OrderId ile ödeme işleminin iptal edilmesini sağlar.

Method Name : void
Http Method : Post
Content-Type : application/json

Request Parametreleri

Response Parametreleri

Örnekler

{
 "OrderId": " A1B2C3D4",
 "ClientId": 1,
 "ApiUser": "****",
 "Rnd": "****",
 "TimeSpan": "20220119111007",
 "Hash": "****",
 "echo": "string"
 }
 

{
 "OrderId": " A1B2C3D4",
 "BankResponseCode": null,
 "BankResponseMessage": null,
 "AuthCode": null,
 "HostReferenceNumber": null,
 "TransactionId": null,
 "Code": 101,
 "Message": "string"
 }

İade

Bankaların gün sonu aldıktan sonra işlemin kısmi veya tam olarak iade edilmesidir. Ödeme işlemini iade eder. Tam iade ve kısmi iade yapılabilmesini sağlar.

Method Name : refund
Http Method : Post
Content-Type : application/json

Request Parametreleri

Response Parametreleri

Örnekler

{
 "OrderId": " A1B2C3D4",
 "Amount": "125",
 "ClientId": 1,
 "ApiUser": "***",
 "Rnd": "***",
 "TimeSpan": "20220119111007",
 "Hash": "***",
 "echo": "string"
 }

{
 "OrderId": " A1B2C3D4",
 "BankResponseCode": null,
 "BankResponseMessage": null,
 "AuthCode": null,
 "HostReferenceNumber": null,
 "TransactionId": null,
 "Code": 101,
 "Message": "string"
 }

Test Kart Bilgileri

Açık Kaynak

WooCommerce, Opencart ve Prestashop e-ticaret yazılımları için hazırlanmış olan entegrasyon modüllerini web sitenize kurarak, Tosla İşim'e kolayca entegre olabilirsiniz.

Ayrıca PHP SDK dosyasını kullanarak özel yazılımlarınıza entegre edebilirsiniz.

Woocommerce Entegrasyonu

Opencart v2.x Entegrasyonu

Opencart v3.x Entegrasyonu

PrestaShop Entegrasyonu (v1.6.x - v1.7.x)

PHP Class v2.1.0

Postman Test Collection Örnekler