Ptt Akıllı Esnaf POS Geliştirici Merkezi

Ortam Bilgileri

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 = "gkk4l2*TY112";
         var ClientId = "1000000032";
         var ApiUser = "Entegrasyon_01";
         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 = "gkk4l2*TY112";
        $clientId = "1000000032";
        $apiUser = "Entegrasyon_01";
        $rnd = rand(1, 10000);
        $timeSpan = time();

        $hashString = $apiPass . $clientId . $apiUser . $rnd . $timeSpan;
        $hashingbytes = hash("sha512", ($hashString), true);
        $hash = base64_encode($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.

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

Request Parametreleri

Response Parametreleri

Örnekler

{
    "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"
} 

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

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.

{
  "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

Alan Adı	Tipi	Max Uzunluk	Zorunlu	Açıklama
ClientId	long	20	Evet	Mağaza İçin belirlenmiş benzersiz numara
ApiUser	string	100	Evet	Api kullanıcı adı
Rnd	string	24	Evet	İşlem için üretilmiş random numara
TimeSpan	string	14	Evet	İşlem tarihi yyyyMMddHHmmss formatında
Hash	string	512	Evet	Güvenlik kontrolünde kullanılacak hash stringi, bir hash bir kez kullanılacaktır.
OrderId	string	20	Opsiyonel	Ön Otorizasyon (PreAuth) işleminde gönderilen Sipariş numarasıdır.
Amount	long	18	Evet	İşlem tutarı
Currency	int	3	Evet	İşlem Para birimi TL için 949
Extraparameters	string	30	Opsiyonel	Application channel bilgisi

Response Parametreleri

Alan Adı	Tipi	Max Uzunluk	Açıklama
Code	int	3	0 ise İşlem başarılıdır. Diğer numaralar hatalıdır.
Message	string	256	İşleme ait mesaj
OrderId	string	20	Sipariş Numarasıdır. Belirlenmediği takdirde sistem otomatik üretecektir.

Örnekler

Request	Response
{ "clientId": 1, "apiUser": "testUser", "rnd": "***", "timeSpan": "20191121160000", "hash": "***", "orderId": "12345678901234567890", "amount": 2211, "extraparameters": "abc" }	{ "code": 0, "message": "Başarılı", "orderId": "12345678901234567890" }

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.

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>

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": ""
}

Ödeme Sorgulama

Ptt Akıllı Esnaf POS ta 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": 1000000032,
      "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, Magento ve Prestashop e-ticaret yazılımları için hazırlanmış olan entegrasyon modüllerini web sitenize kurarak, Ptt Akıllı Esnaf'a kolayca entegre olabilirsiniz.

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

Ptt Akıllı Esnaf POS Woocommerce Entegrasyonu

Ptt Akıllı Esnaf POS Opencart v2.x Entegrasyonu

Ptt Akıllı Esnaf POS Opencart v3.x Entegrasyonu

Ptt Akıllı Esnaf POS PrestaShop Entegrasyonu (v1.6.x - v1.7.x)

• Ptt Akıllı Esnaf POS PHP Class v2.1.0

Postman Test Collection Örnekler