PTT Akıllı Esnaf Geliştirici Merkezi

PTT Akıllı Esnaf’a entegre olurken her adımınızda sizlere yardımcı olabilmemiz için Geliştirici Merkezi’ne göz atabilir ya da entegrasyon kapsamında sorun yaşamanız durumunda destek@akilliesnaf.gov.tr mail adresinden destek alabilirsiniz.

Genel Bakış

API entegrasyonunda üye işyeri kendi ödeme formunu kullanır. Bu form üzerindeki kontrolleri ve kuralları uygulaması gerekir.

  • Kart numarası(PAN) luhn algoritmasına tabi tutulmalıdır.
  • Kartın hamilinin adı ve soyadı alınmalıdır.
  • Son kullanma tarihi geçmiş kartlar ile API'ye sorgu yapılmamalıdır.
  • AMEX kartları ile işlem alabilir şekilde tasarlanmalıdır.

3D ile Ödeme

Tek çekim, taksitli ve tek tıkla ödeme işlemleri için uygundur. İşleme gönderilen kartın bakiyesinden ilgili miktarı çekme işlemi yapar. 3D secure başlatılması için session açar ve sessionId döner. Bu servisten dönen threeDsessionId iframe yöntemiyle 3Dyönlendirme servis url’ine eklenerek 3D doğrulama akışının yapılması sağlanır. Eğer 3D doğrulama başarılı ise Sistem otomatik olarak ödemeye gönderir.
Taksitli / Taksitsiz işlem yapılabilir.

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

Request Parametreleri
Alan Adı TipiMax UzunlukZorunluAçıklama
clientIdlong20EvetMağaza İçin belirlenmiş benzersiz numara
apiUserstring100EvetApi kullanıcı adı
Rnd string 24 Evetİşlem için üretilmiş random numara
timeSpan string14 Evetİşlem tarihi yyyyMMddHHmmss formatında
Hash string1024 EvetGüvenlik kontrolünde kullanılacak hash stringi, bir hash bir kez kullanılacaktır.
callbackUrl string1024 Evet3D sonucunun dönüleceği url
orderId string20 OpsiyonelSipariş Numarasıdır. Belirlenmediği takdirde sistem otomatik üretecektir.
Amount long19Evetİşlem Tutarı, son iki hane kuruştur. 1522 = 15 TL 22 Kuruş
Currency int3Evet İşlem Para birimi 949
installmentCount int2 Opsiyonel Default “0”

Response Parametreleri
Alan Adı TipiMax UzunlukAçıklama
Code int 7 0 ise İşlem başarılıdır. Diğer numaralar hatalıdır.
Message string 256 İşleme ait mesajdır
threeDSessionId string2563D işlem için üretilen Unqiue numara

Örnekler
Request Response
{
    "clientId": 1,
    "apiUser": "testUser",
    "rnd": "***",
    "timeSpan": "20191121160000",
    "hash": "***",
    "orderId": "12345678901234567890",
    "callbackUrl": "***merchantCallbackUrl***",
    "amount": 100,
    "currency": 949,
    "installmentCount": 0
  }
{
   "code": 0,
   "message":
   "Başarılı",
   "threeDSessionId":
   "***"
 } 

3D ile Ödeme için Json Format Örneği
{
   "orderId": "string",
   "amount": 0,
   "currency": 0,
   "installmentCount": 0,
   "callbackUrl": "string",
   "description": "string",
   "clientId": 0,
   "apiUser": "string",
   "rnd": "string",
   "timeSpan": "string",
   "hash": "string"
 }

Ö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
Alan Adı TipiMax UzunlukZorunluAçıklama
clientIdlong20EvetMağaza İçin belirlenmiş benzersiz numara
apiUserstring100EvetApi kullanıcı adı
Rnd string 24 Evetİşlem için üretilmiş random numara
timeSpan string14 Evetİşlem tarihi yyyyMMddHHmmss formatında
Hash string1024 EvetGüvenlik kontrolünde kullanılacak hash stringi, bir hash bir kez kullanılacaktır.
orderId string20 EvetÖn Otorizasyon (PreAuth) işleminde gönderilen Sipariş numarasıdır.

Response Parametreleri
Alan Adı TipiMax UzunlukAçıklama
Code int 7 0 ise İşlem başarılıdır. Diğer numaralar hatalıdır.
Message string 256 İşleme ait mesajdır
Payments list İşleme ait ödeme listesini döner.

Örnekler
Request Response
{
    "clientId": 1,
    "apiUser": "testUser",
    "rnd": "***",
    "timeSpan": "20191121160000",
    "hash": "***",
    "orderId": "12345678901234567890"
  } 
{
    "code": 0,
    "message": "Başarılı",
    "payments": [
                  {
                    "createDate":
                    "20151012112230",
                    "orderId":
                    "12345678901234567890",
                    "code": 0,
                    "message":
                    "Success",
                    "bankCode":
                    111,
                    "amount":
                    22.11,
                    "currency":
                    "949",
                    "clientId": 1
                  }
               ]
  }

İ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
Alan Adı TipiMax UzunlukZorunluAçıklama
clientIdlong20EvetMağaza İçin belirlenmiş benzersiz numara
apiUserstring100EvetApi kullanıcı adı
Rnd string 24 Evetİşlem için üretilmiş random numara
timeSpan string14 Evetİşlem tarihi yyyyMMddHHmmss formatında
Hash string1024 EvetGüvenlik kontrolünde kullanılacak hash stringi, bir hash bir kez kullanılacaktır.
orderId string20 ZorunluÖn Otorizasyon (PreAuth) işleminde gönderilen Sipariş numarasıdır.

Response Parametreleri
Alan Adı TipiMax UzunlukAçıklama
Code int 7 0 ise İşlem başarılıdır. Diğer numaralar hatalıdır.
Message string 256 İşleme ait mesajdır
orderId string 20Sipariş Numarasıdır.

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

İ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
Alan Adı TipiMax UzunlukZorunluAçıklama
clientIdlong20EvetMağaza İçin belirlenmiş benzersiz numara
apiUserstring100EvetApi kullanıcı adı
Rnd string 24 Evetİşlem için üretilmiş random numara
timeSpan string14 Evetİşlem tarihi yyyyMMddHHmmss formatında
Hash string1024 EvetGüvenlik kontrolünde kullanılacak hash stringi, bir hash bir kez kullanılacaktır.
orderId string20 EvetÖn Otorizasyon (PreAuth) işleminde gönderilen Sipariş numarasıdır.
Amount long19 Evetİade İşlem Tutarı, son iki hane kuruştur. 1522 = 15 TL 22 Kuruş

Response Parametreleri
Alan Adı TipiMax UzunlukAçıklama
Code int 7 0 ise İşlem başarılıdır. Diğer numaralar hatalıdır.
Message string 256 İşleme ait mesajdır
orderId string 20Sipariş Numarasıdır.

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

İş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
Alan Adı TipiMax UzunlukZorunluAçıklama
clientIdlong20EvetMağaza İçin belirlenmiş benzersiz numara
apiUserstring100EvetApi kullanıcı adı
Rnd string 24 Evetİşlem için üretilmiş random numara
timeSpan string14 Evetİşlem tarihi yyyyMMddHHmmss formatında
Hash string1024 EvetGüvenlik kontrolünde kullanılacak hash stringi, bir hash bir kez kullanılacaktır.
reconciliationDate int8 Evetİşlem yapılan tarihtir. yyyyMMdd
Page intint max EvetPaging yapısı gereği kullanılan sayfa numarası ilk sayfa için 1, ikinci sayfa için 2...
pageSize int3 EvetPaging yapısı gereği kullanılan sayfa başı kayıt sayısı.

Response Parametreleri
Alan Adı TipiMax UzunlukAçıklama
Code int 7 0 ise İşlem başarılıdır. Diğer numaralar hatalıdır.
Message string 256 İşleme ait mesajdır
count int int maxTarih filtresine uygun toplam kayıt sayısını döner.
payments list İşleme ait ödeme listesini döner.

Örnekler
Request Response
{
    "clientId": 1,
    "apiUser": "testUser",
    "rnd": "***",
    "timeSpan": "20191121160000",
    "hash": "***",
    "reconciliationDate": "20200101"
    "page": "1"
    "pageSize": "10"
  } 
{
    "code": 0,
    "message": "Başarılı",
    "payments": [
                  {
                    "createDate": "20151012112230",
                    "orderId": "12345678901234567890",
                    "code": 0,
                    "message": "Success",
                    "bankCode": 111,
                    "amount": 22.11,
                    "currency": "949",
                    "clientId": 1
                  }
                ]
}

Ortak Ödeme Sayfası

Server tarafından startThreeDSession servisi ile threeDSessionId alınarak client tarafına iletilir. client tarafında browser aracılığıyla threeDSecure url’ine get işlemi gerçekleştirilir. Parametre olarak threeDSessionId değerleri eklenir.

threeDSessionId 3D doğrulama işleminde kullanılan benzersiz değerdir.

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

İşlem sonucunu threeDSessionResult servisinden de öğrenebilirsiniz.

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

Request Parametreleri

<iframe src="https://******/threeDSecure/{threeDSessionId}" height="250" width="400"></iframe>

Hash Mekanizması

private string CreateHash()
{
   var ApiKey = "";
   var ClientId = "";
   var ApiUser = "";
   var Rnd = "";
   var TimeSpan = "";
   var hashString =ApiKey + 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;
}

Ortam ve Test Kart Bilgileri

Test Ortam URLhttps://prepaeo.ptt.gov.tr/
ClientId 1000000032
Apikey Entegrasyon_01
ApiPass gkk4l2*TY112

* Production (Üretim) ortamı için bilgiler entegrasyonunuz tamamlandıktan sonra iletilecektir.

Test Kartları
Kart No Son Kullanım TarihiCVV3D Secure Şifre
411979015520349604/24579123456
411979016654428404/24961123456
409070010117427212/22104
409070009084005711/22592

Hata Kodları ve Açıklamaları

Method Türkçe Hata Mesajıİngilizce Hata Mesajı
Voidthrow new ApiException(MessageCodes.UnauthorizedOperationForMerchant ApiUser) --> UnauthorizedOperationForMerchantApiUser = 250
Orjinal Kayıt BulunamadıOriginal Not Found
BaşarılıSuccess
HatalıFail
Refundthrow new ApiException(MessageCodes.UnauthorizedOperationForMerchant ApiUser) -->
İade Tutarı Satış Tutarından Büyük OlamazRefund Amount Error
Toplam İade Edilecek Tutar Satış Tutarından Büyük OlamazRefunded Amount Error
throw new ApiException(MessageCodes.MerchantNotFound) --> MerchantNotFound = 200
BaşarılıSuccess
HatalıFail
Historythrow new ApiException(MessageCodes.UnauthorizedOperationForMerchant ApiUser) --> UnauthorizedOperationForMerchantApiUser = 250
BaşarılıSuccess
ThreeDPaymentthrow new ApiException(MessageCodes.UnauthorizedOperationForMerchant ApiUser) --> UnauthorizedOperationForMerchantApiUser = 250
Orjinal Kayıt BulunamadıOriginal Not Found
BaşarılıSuccess
Inquirythrow new ApiException(MessageCodes.UnauthorizedOperationForMerchant ApiUser) --> UnauthorizedOperationForMerchantApiUser = 250

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.