PTT Akıllı Esnaf Geliştirici Merkezi

Genel Bakış

Geliştirici merkezindeki adımlar takip edilerek, PTT Akıllı Esnaf servislerine entegre olabilirsiniz.
Son Güncelleme Tarihi: Ekim 2022 Versiyon: v2.1.0

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
• PHP

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;
}

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

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

PTT Akıllı Esnaf Opencart Entegrasyonu (v2.x - v3.x)

PTT Akıllı Esnaf Magento Entegrasyonu

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

• PTT Akıllı Esnaf PHP SDK v2.1.0
• PTT Akıllı Esnaf PHP Class v2.1.0

Postman Test Collection Örnekler