Ptt Akıllı Esnaf POS 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.ptt.gov.tr mail adresinden destek alabilirsiniz.

Ortam Bilgileri

Test ortam bilgilerini kullanabilmeniz için test ortamınızın IP bilgilerinin tanımlanması gerekmektedir. Bilgilerinizi destek@akilliesnaf.ptt.gov.tr maili üzerinden göndererek tanımlamalar konusunda destek alabilirsiniz
Test Ortam URL https://prepaeo.ptt.gov.tr/api/Payment/
ClientId 1000000032
ApiUser Entegrasyon_01
ApiPass gkk4l2*TY112

Production (Üretim) Ortam URL
* 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.

Alan Adı Tipi Açıklama Örnek Değer
ClientId long API müşteri numaranız 1000000032
ApiUser string API kullanıcı adınız Entegrasyon_01
Rnd string (max 24) İşlem için üretilmiş random değer 123456ABC
TimeSpan string İşlem tarihi (yyyyMMddHHmmss) 20221012010436
Hash string Güvenlik kontrolünde kullanılacak hash stringi, her hash sadece bir kez kullanılacaktır. Hash üretim adımını inceleyiniz

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.

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.

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
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.
CallbackUrl string 1024 Evet 3D sonucunun dönüleceği url
OrderId string 20 Opsiyonel Sipariş Numarasıdır. Belirlenmediği takdirde sistem otomatik üretecektir.
Amount long 18 Evet İşlem Tutarı, son iki hane kuruştur. 1522 = 15 TL 22 Kuruş
Currency int 3 Evet İşlem Para birimi 949
InstallmentCount int 2 Opsiyonel Default “0”
Description string 256 Opsiyonel İşleme ait açıklama
Echo string 256 Opsiyonel İstek sonucunda geri gönderilecek bilgi alanı
ExtraParameters string 4000 Opsiyonel

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
threeDSessionId string 1024 3D işlem için üretilen Unqiue numara
transactionId string 20 İşlem ID'si

Örnekler
Request Response
{
    "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"
} 

CODE MESSAGE Validation Errors AÇIKLAMA
0 Başarılı
202 Üye İşyeri Kullanıcısı Bulunamadı
250 Üye İşyeri Api Kullanıcısı için Yetkisiz İşlem
997 Hash Hatası
998 Validasyon Hatası 'Time Span' alanı yyyyMMddHHmmss formatında olmalıdır.
'Time Span' alanı 60 dakidan büyük olamaz, mevcut dakika fark: 240.
An undefined token is not a valid System.Nullable`1[System.Int64]. Path 'amount', line 3, position 12." Zorunlu alan boş gönderildiğinde alınan hata

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
Input Name Zorunlu Açıklama
threeDSessionId Evet Ödeme işlem başlatma adımında oluşturduğunuz threeDSessionId değeri
CardHolderName Evet Kart hamilinin adı ve soyadı
CardNo Evet Kredi kart numarası
ExpireDate Evet Kart son kullanım tarihi (AA/YY)
Cvv Evet Kart güvenlik kodu

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

CODE MESSAGE Validation Errors AÇIKLAMA
0 Başarılı
1 AlreadyBankResponse İşlem ekranında kayıtlı işleme ait BankResponseCode is not null
1 Tutar Sıfır Olamaz İşlemler ekranında kayıtlı işlemde Amount=0 ise
998 Validasyon Hatası After parsing a value an unexpected character was encountered: \". Path 'additionalProp3', line 5, position 1.
0824' is not a valid number. Path 'additionalProp4', line 5, position 25.
999 Genel Hata

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
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.
CallbackUrl string 1024 Evet ProcessCardForm işlem sonucunun dönüleceği url
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
ThreeDSessionId string 256 3D işlem için üretilen Unqiue numara
TransactionId string 256 3D işlem için üretilen Unqiue numara

Örnekler
Request Response
{
  "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"
}

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
Alan Adı Tipi Max Uzunluk Zorunlu Açıklama
cardHolderName String 100 Evet Kart hamilinin adı ve soyadı
cardNo String 16 Evet Kredi kartı numarası
expireDate String 4 Evet Kart son kullanım tarihi (AAYY) ör: 1224
cvv String 4 Evet Kart güvenlik kodu
clientId long 19 Evet Mağaza İçin belirlenmiş benzersiz numara
apiUser string 100 Evet Api kullanıcı adı
rnd string 24 Evet İşlem için üretilmiş random değer. hash içerisinde kullanılan değer ile aynı olmalıdır.
timeSpan string 14 Evet İşlem tarihi (yyyyMMddHHmmss). hash içerisinde kullanılan değer ile aynı olmalıdır. İşlem anında verilen tarih ve saat bilgisi olmalıdır. GTM+3 zaman diliminde ve max 1 saat farka izin verilmektedir. Diğer durumlarda hash hatası alınır.
hash string 512 Evet Güvenlik kontrolünde kullanılacak hash stringi, bir hash bir kez kullanılacaktır.
orderId string 20 Opsiyonel Sipariş Numarasıdır. Belirlenmediği takdirde sistem otomatik üretecektir.
isCommission long 18 Opsiyonel isCommission değeri 1 gönderildiği durumlarda zorunludur. totalAmount değeri GetInstallmentOptions’ta dönen taksite karşılık gelen değer gönderilmelidir. isCommission değeri 1 gönderildiğinde bankaya gönderilen tutardır, son iki hane kuruştur. 1528 = 15 TL 28 Kuruş
amount long 18 Evet İşlem Tutarı, son iki hane kuruştur. 1522 = 15 TL 22 Kuruş
totalAmount long 18 Opsiyonel isCommission değeri 1 gönderildiği durumlarda zorunludur. totalAmount değeri GetInstallmentOptions’ta dönen taksite karşılık gelen değer gönderilmelidir. isCommission değeri 1 gönderildiğinde bankaya gönderilen tutardır, son iki hane kuruştur. 1528 = 15 TL 28 Kuruş
currency int 3 Evet İşlem Para birimi 949
installmentCount int 2 Opsiyonel Default “0”
description string 256 Opsiyonel İşleme ait açıklama
echo string 256 Opsiyonel Echo bilgisi
extraParameters string 4000 Opsiyonel Ekstra bilgilerin gönderildiği alan. Inquiry servisi cevabında döner

Response
Alan Adı Açıklama
Code 0 ise İşlem başarılıdır. Diğer numaralar hatalıdır.
Message İşleme ait mesaj
orderId İşlemin sipariş numarası
BankResponseCode Banka tarafındaki işlem statü kodu. 00 ise başarılı diğer tüm durumlar başarısız olarak kabul edilir.
BankResponseMessage Banka tarafındaki işlem statü mesajı
AuthCode İşlemin bankadaki otorizasyon kodu
HostReferenceNumber Host Reference Number
TransactionId İşlemin sistemdeki numarası
CardHolderName İşlemde kullanılan kartın hamili
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
Request Response
{
    "clientId": 1,
    "apiUser": "testUser",
    "rnd": "***",
    "timeSpan": "20191121160000",
    "hash": "***",
    "CardHolderName":"Test Test",
    "cardNo": "4159560047417732",
    "expireDate": "0824",
    "cvv": "123",
    "description": "açıklama",
    "orderId": "12345678901234567890",
    "amount": 00000,
    "currency": 949,
    "installmentCount":0,
}
{
 "OrderId": "12345678901234567890",
 "BankResponseCode": "00",
 "BankResponseMessage": "Başarılı",
 "AuthCode": "*****",
 "HostReferenceNumber":"****",
 "TransactionId": "*****",
 "CardHolderName":":"*****",
 "Code": 0,
 "Message": "Başarılı"
}

Örnekler - Komisyon Yansıtıldığı Durum
Request Response
{
    "clientId": 1,
    "apiUser": "testUser",
    "rnd": "***",
    "timeSpan": "20191121160000",
    "hash": "***",
    "CardHolderName":"Test Test",
    "cardNo": "4159560047417732",
    "expireDate": "0824",
    "cvv": "123",
    "description": "açıklama",
    "orderId": "12345678901234567890",
    "isCommission ":1,
    "amount": 00000,
    " totalAmount "102,
    "currency": 949,
    "installmentCount":0,
}
{
    "code": 0,
    "message": "Başarılı",
    "ThreeDSessionId": "***",
    "transactionId": "12345"
}

CODE MESSAGE Validation Errors
0 Başarılı
100 Ödeme Hatalı
202 Üye İşyeri Kullanıcısı Bulunamadı
250 Üye İşyeri Api Kullanıcısı için Yetkisiz İşlem
997 hash hatası
998 Validasyon Hatası 'Time Span' alanı yyyyMMddHHmmss formatında olmalıdır.
'Time Span' alanı 60 dakidan büyük olamaz, mevcut dakika fark: xxx.
999 Genel Hata İstenmeyen bir durumda alınan hatadır.

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
Alan Adı Tipi Max Uzunluk Zorunlu Açıklama
ThreeDSessionId string 256 Evet 3D işlem için üretilen Unqiue numara

<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
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.
Bin int 6 Evet Kredi kartının ilk 6 hanesidir.

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
CardPrefix int 6 Bin numarası
BankId int 3 Sistemdeki banka ID değeri
BankCode string 512 Banka kodu
BankName string 512 Banka adı
CardName string 512 Kart adı
CardClass string 512 Kart sınıfı
CardType string 512 Kart tipi
Country string 200 Kart ülkesi
BankCommission int 6 Banka komisyonu
InstallmentInfo string Taksit listesi ve komisyon oranı

Örnekler
Request Response
{
  "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
Alan AdıTipiMax UzunlukZorunluAçıklama
ClientIdlong20EvetMağaza İçin belirlenmiş benzersiz numara
ApiUserstring100EvetApi kullanıcı adı
Rndstring24Evetİşlem için üretilmiş random numara
TimeSpanstring14Evetİşlem tarihi yyyyMMddHHmmss formatında
Hashstring512EvetGüvenlik kontrolünde kullanılacak hash stringi, bir hash bir kez kullanılacaktır.
OrderIdstring20EvetÖn Otorizasyon (PreAuth) işleminde gönderilen Sipariş numarasıdır.
TransactionIdstring20OpsiyonelSorgulanacak işlemin Id’si

Response Parametreleri
Alan AdıTipiMax UzunlukAçıklama
Codeint30 ise İşlem başarılıdır. Diğer numaralar hatalıdır.
Messagestring256İşleme ait mesaj
TransactionTypeint653D işlem için Üretilen Unqiue numara
CreateDatestring23Oluşturma tarihi
OrderIdString20Sipariş numarasıdır
BankResponseCodeString7Bankadan alınan cevap kodu
BankResponseMessageString512Bankadan alınan cevap mesajı
AuthCodeString200Otorizasyonda kullanılan kodu
HostReferenceNumberstring200
Amountlong18İşlem tutarı
Currencyint3İşlem Para birimi 949
InstallmentCountint2Taksit sayısı
ClientIdlong20Mağaza İçin belirlenmiş benzersiz numara
CardNostring19Kart Numarası
RequestStatusint2İşlem durumunu gösterir
RefundedAmountLong18İade edilen miktar
PostAuthedAmountLong18Ön Otorizasyon işlemindeki tutar
TransactionIdLong20İşlem İD’si
CommissionStatusInt1Komisyon durumu
NetAmountLong18Net tutar
MerchantCommissionAmountLong18Üye iş yerinin komisyon miktarı
MerchantCommissionRatedecimal18Üye iş yerinin komisyon oranı
CardBankIdLong20Kullanılan banka id’si
CardTypeIdlong20Kullanılan kart tipi id’si
ValorDateint8Valör günü
TransactionDateint8İşlem yapılan tarihtir. yyyyMMdd
BankValorDateint8 
ExtraParametersstring4000 

Örnekler
RequestResponse
{
    "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ı"
}

CODE MESSAGE Validation Errors AÇIKLAMA
0
202 Üye İşyeri Kullanıcısı Bulunamadı
250 Üye İşyeri Api Kullanıcısı için Yetkisiz İşlem
997 Hash Hatası
998 Validasyon Hatası Time Span' alanı yyyyMMddHHmmss formatında olmalıdır.
Time Span' alanı 60 dakidan büyük olamaz, mevcut dakika fark: 1050626
Unexpected character encountered while parsing value: ,. Path 'orderId', line 2, position 14. Zorunlu alan boş gönderildiğinde alınan hata
An undefined token is not a valid System.Int64. Path 'clientId', line 3, position 14. Zorunlu alan boş gönderildiğinde alınan hata
999 Genel Hata

İş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ı
Rndstring24Evetİşlem için üretilmiş random numara
TimeSpanstring14Evetİşlem tarihi yyyyMMddHHmmss formatında
OrderIdstring20OpsiyonelSipariş numarası
Hashstring512EvetGüvenlik kontrolünde kullanılacak hash stringi, bir hash bir kez kullanılacaktır.
TransactionDateint8Evetİşlem yapılan tarihtir. yyyyMMdd
Pageintint maxEvetPaging yapısı gereği kullanılan sayfa numarası ilk sayfa için 1, ikinci sayfa için 2...
PageSizeint3EvetPaging yapısı gereği kullanılan sayfa başı kayıt sayısı.

Response Parametreleri
Alan AdıTipiMax UzunlukAçıklama
Codeint30 ise İşlem başarılıdır. Diğer numaralar hatalıdır.
Messagestring256 İşleme ait mesaj
Countintint maxTarih filtresine uygun toplam kayıt sayısını döner.
Transactionslistİşleme ait ödeme listesini döner.

Örnekler
RequestResponse
{
  "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": ""
    }
  ]
}

CODE MESSAGE Validation Errors AÇIKLAMA
0 Başarılı
250 Üye İşyeri Api Kullanıcısı için Yetkisiz İşlem
998 Validasyon Hatası Time Span' alanı yyyyMMddHHmmss formatında olmalıdır.
Time Span' alanı 60 dakidan büyük olamaz, mevcut dakika fark: 1050626
Unexpected character encountered while parsing value: ,. Path 'orderId', line 2, position 14. Zorunlu alan boş gönderildiğinde alınan hata
An undefined token is not a valid System.Int64. Path 'clientId', line 3, position 14. Zorunlu alan boş gönderildiğinde alınan hata
999 Genel Hata

İ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ı
Rndstring24Evetİşlem için üretilmiş random numara
TimeSpanstring14Evetİşlem tarihi yyyyMMddHHmmss formatında
Hashstring512EvetGüvenlik kontrolünde kullanılacak hash stringi, bir hash bir kez kullanılacaktır.
OrderIdstring20EvetÖn Otorizasyon (PreAuth) işleminde gönderilen Sipariş numarasıdır.
Echostring256Opsiyonelİstek sonucunda geri gönderilecek bilgi alanı

Response Parametreleri
Alan AdıTipiMax UzunlukAçıklama
Codeint30 ise İşlem başarılıdır. Diğer numaralar hatalıdır.
Messagestring256 İşleme ait mesaj
OrderIdstring20Sipariş Numarasıdır.
BankResponseCodestring7Bankadan alınan cevap kodu
BankResponseMessagestring512Bankadan alınan cevap mesajı
AuthCodestring200Otorizasyonda kullanılan kodu
HostReferenceNumberstring200Ödeme kanalın referans numarası
TransactionIdlong20İşlem İD’si

Örnekler
RequestResponse
{
  "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"
}

CODE MESSAGE Validation Errors AÇIKLAMA
0 Başarılı
1 Iptal etmek istediğiniz tutar, hakkediş tutarınızdan fazladır. 10,00 tutarından daha fazla iptal/iade yapamazsınız.
1 Başarılı bir postauth olduğu için ön otorizasyon işlemini iptal edemezsiniz.
101 Orjinal Kayıt Bulunamadı
202 Üye İşyeri Kullanıcısı Bulunamadı
250 Üye İşyeri Api Kullanıcısı için Yetkisiz İşlem
997 Hash Hatası
998 Validasyon Hatası Time Span' alanı yyyyMMddHHmmss formatında olmalıdır.
'Time Span' alanı 60 dakidan büyük olamaz, mevcut dakika fark: 240.
Unexpected character encountered while parsing value: ,. Path 'orderId', line 2, position 14. Zorunlu alan boş gönderildiğinde alınan hata
An undefined token is not a valid System.Int64. Path 'clientId', line 3, position 14. Zorunlu alan boş gönderildiğinde alınan hata
999 Genel Hata

İ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ı
Rndstring24Evetİşlem için üretilmiş random numara
TimeSpanstring14Evetİşlem tarihi yyyyMMddHHmmss formatında
Hashstring512EvetGüvenlik kontrolünde kullanılacak hash stringi, bir hash bir kez kullanılacaktır.
OrderIdstring20EvetÖn Otorizasyon (PreAuth) işleminde gönderilen Sipariş numarasıdır.
Amountlong18Evetİade İşlem Tutarı, son iki hane kuruştur. 1522 = 15 TL 22 Kuruş
Echostring256Opsiyonelİstek sonucunda geri gönderilecek bilgi alanı

Response Parametreleri
Alan AdıTipiMax UzunlukAçıklama
Codeint30 ise İşlem başarılıdır. Diğer numaralar hatalıdır.
Messagestring256 İşleme ait mesaj
OrderIdstring20Sipariş Numarasıdır.
BankResponseCodestring7Bankadan alınan cevap kodu
BankResponseMessagestring512Bankadan alınan cevap mesajı
AuthCodestring200Otorizasyonda kullanılan kodu
HostReferenceNumberstring200Ödeme kanalın referans numarası
TransactionIdlong20İşlem İD’si

Örnekler
RequestResponse
{
  "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"
}

CODE MESSAGE Validation Errors AÇIKLAMA
0 Başarılı
1 İade etmek istediğiniz tutar, hakkediş tutarınızdan fazladır. 10,00 tutarından daha fazla iade yapamazsınız.
100 Ödeme Hatalı
101 Orjinal Kayıt Bulunamadı
103 İade Tutarı Satış Tutarından Büyük Olamaz
104 RefundedAmountError iade edilen tutar ve işlemde daha önce iade edilmiş olan tutarların toplamından işlemde yapılan ödeme miktarından büyük ise
200 Üye İşyeri Bulunamadı
250 Üye İşyeri Api Kullanıcısı için Yetkisiz İşlem
400 Cvv Format Hatası.
401 Expire Date Format Hatası.
402 Card No Format Hatası.
997 Hash Hatası
998 Validasyon Hatası Time Span' alanı yyyyMMddHHmmss formatında olmalıdır.
'Time Span' alanı 60 dakidan büyük olamaz, mevcut dakika fark: 240.
Unexpected character encountered while parsing value: ,. Path 'orderId', line 2, position 14. Zorunlu alan boş gönderildiğinde alınan hata Zorunlu alan boş gönderildiğinde alınan hata
An undefined token is not a valid System.Int64. Path 'clientId', line 3, position 14. Zorunlu alan boş gönderildiğinde alınan hata
999 Genel Hata

Test Kart Bilgileri

Kart NoSon Kullanım TarihiCVV3D Secure Şifre
415956004741773208/24123-
557113557113557512/22000-

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.