Paycell SDK Nedir?
Paycell WEB SDK Entegrasyonu
Paycell Mobil SDK Entegrasyon
Paycell SDK RESTful Servisleri
Örnek Kodlar
Test Kredi Kartları

Paycell SDK Nedir?

  • Paycell, e-ticaret işyerlerinin kolayca ödeme alabilmesini sağlayan, son kullanıcıya sunduğu alternatif ödeme çözümleriyle de farklı ihtiyaçları karşılayabilen kapsayıcı bir ödeme platformudur.

  • Bu dokümanda anlatılan “Paycell ile Öde” ürünü içerisinde, müşteriler;
    • Paycell’e daha önce kaydettikleri kredi kartlarını ya da yeni ekleyecekleri kartlarını kullanarak,
    • Turkcell Faturasına yansıtarak (Turkcell Mobil Ödeme),
    • Paycell Dijital Para bakiyelerini kullanarak ve
    • Paycell Kart’larındaki bakiyelerini kullanarak ödeme yapabilirler.

  • Ödeme araçları, üye işyeriyle yapılan anlaşmalara ve son kullanıcının hesabında tanımlı ödeme araçlarına göre değişebilir ve kredi kartlarıyla yapılan ödemelerde üye işyerinin sanal POS’larının tanımına göre taksit opsiyonları sunularak da ödeme yapılabilir.

  • İş yerinin online ortamdaki satış mecrasında, ödeme sayfasında ödeme seçeneği olarak “Paycell ile Öde” konumlandırılır. Kullanıcı Paycell ile ödeme yapmak istediğinde Paycell ekranları iframe ya da lightbox olarak açılır. Ödeme sayfasına kullanıcı, telefon numarası ile giriş yapar. Ardından kullanıcının telefonuna doğrulama kodu gelir, müşteri doğrulama şifresini girdikten sonra Paycell uygulamasından oluşturduğu Paycell şifresi var ise şifreyi girip devam eder. Eğer şifresi yok ise devam ettiğinde kullanıcının telefon numarasıyla eşlemiş ödeme tipleri sayfada gösterilir.Bunlar; kredi kartı ile ödeme, Turkcell Hattınla Ödeme, ,Dijital Para ile ödeme ve Paycell Kart ile ödemedir.

  • Paycell ile Öde” platformu mobil platformlar iOS ve Android için native olarak hazırlanmıştır. Ek olarak web siteleri veya web tabanlı uygulamalar için de Web platformlarına uygun SDK’ları da geliştirilmiştir. Bu doküman Web SDK platformu için hazırlanmış, Web SDK platformuna “Paycell ile Öde”nin nasıl entegre edileceği anlatılmaktadır.

Paycell entegrasyonu genel yapısı

Paycell Web SDK entegrasyonu için Paycell tarafından sağlanması gereken bilgiler;
  1. Merchant Code
  2. Terminal Code
  3. Secure Code
  4. Application Name
  5. Application Password

Paycell Web SDK’ya atacağınız requestleri göndereceğiniz URL’ler:
https://websdktest.turkcell.com.tr/api/session/init
https://websdktest.turkcell.com.tr/home/[trackingId]
Paycell Web SDK, Init ve Status servislerinden meydana gelmektedir.
  1. Init Servisi: Ödeme işlemi başlatılıp alınan tracking ID ile Paycell arayüzüne erişim sağlanır.
  2. Validation: Kullanıcının Paycell sistemine giriş yapıp ödemesini tamamlaması sağlanır.
  3. Status servisi: Başlatılan ödemenin son durumu hakkında sorgulama yapılır.
 
Üye iş yeri, yapacağı SDK entegrasyonu ile Paycell servislerine erişim sağlamış olacaktır. Akış şu sırada ilerleyecektir.
  • Üye iş yeri uygulamasında, doğrulanmış bir kullanıcı ödeme adımında “Turkcell Paycell ile Öde” butonuna basar.
  • Üye işyeri uygulaması “init” servisini çağırır. (https://websdktest.turkcell.com.tr/api/session/init )
  • Init servisi cevabında işlem başarılı olursa trackingID üretilir.
  • TrackingID bilgisi kullanılarak https://websdktest.turkcell.com.tr/home/[trackingId] linkin sonuna TrackingID eklenerek kullanıcı, sayfaya iframe içinde ya da yeni sekmede açılarak yönlendirilir.
  • Bu sayfanın yönlendirilmesi ile üye iş yeri, arka planda trackingID bilgisini kullanarak Status servisini çağırır ve işlemin sonucunu başarılı ya da başarısız olarak öğrenmek için sürekli sorgular.
  • Status’ten gelecek sonuç enum tipindedir. 0 için SUCCESS, 1 için PENDING, 2 için CANCELLED ve 3 için NOTFOUND değerlerinden biridir.
  • Sonucun alınması ile üye iş yeri sonuç bilgisini kullanıcıya gösterir.

Init Service nasıl çalışır?

Parametreler :
URL : https://websdktest.turkcell.com.tr/api/session/init
 
Name Type M/O Description
requestHeader RequestHeader Mandatory Üye iş yeri, ve işlem bilgileri Paycell Web SDK Nedir? kısmını inceleyebilirsiniz
hashData string Mandatory Bununla ilgili Paycell Entegrasyon kısmını inceleyebilirsiniz.
hostAccount string Mandatory Üye iş yeri uygulamasında ödemeyi yapan kullanıcıyı tekil olarak ifade eden değerdir. Üye işyeri uygulamasında kullanıcı doğrulaması mail adresi ile yapılıyorsa bu alanda mail adresi gönderilebilir.
language string Mandatory Dil bilgisi. tr/en
payment Payment Mandatory Ortak Sınıflar başlığını inceleyebilirsiniz.
returnUrl string Mandatory ReturnUrl, ödeme işlemi gerçekleştikten sonra kullanıcıyı üye işyerine yönlendirecek URL’yi içerir. Ödeme işlemi tamamlandığında sdk tarafından returnUrl ’e redirect  yapılır. Bu url dinlenerek status servis sorgulanmadan işlemin bittiği anlaşılabilir.  
postResultUrl string Mandatory Bu URL’e işlem başarılı , başarısız olarak tamamlandığında veya timeout alıdığında Paycell WEB SDK tarafından ödemeye ait bilgi ve statü post edilir. Burada gleen bilgiler Üye işyeri tarafından yorumlanarak aksiyon alınabilir.
timeoutDuration string Mandatory Üye işyerinin alışveriş için verdiği toplam zamandır


Örnek Request :
{  
"requestHeader": 
{    
"merchant":
{
 "merchantCode": "sample",      
"terminalCode": "sample"    
},    
"transactionInfo": 
{      
"transactionDateTime": "20170126174611094",      
"transactionId": "20170126174611094755"  
 }  
},  
"hashData": "VDoZFXn4V\/mSrJ0I2RLUZkM6J2Y=",  
"hostAccount": "xxxxxxxx@xxxx.com",  
"language": "tr",  
"payment": 
{    
"amount": "600",    
"currency": "99",    
"paymentReferenceNumber": "53df74fd-24bd-4370-90f5-9e896acc872c",    
"paymentSecurity": "NON_THREED_SECURE",    
"installmentPlan": [      
{       
 "lineId": "1",       
 "paymentMethodType": "CREDIT_CARD",        
"cardBrand": "BONUS",        
"count": "1",       
 "amount": "600"     
 },    
]  }, 
"returnUrl": null
}
 

Response :
{
"trackingId": "d791ce6a64b94c83afafe7387d236e20",
"statusCode": "0",
"message": "Success"
}

Turkcell Hızlı Giriş ile Login Olmuş Kullanıcı’nın SDK’ya Girişi

Turkcell Hızlı Giriş ile üye işyerine giriş yapmış bir kullanıcı, ödeme adımında Paycell İle Öde seçeneğini seçer ise, Üye İşyeri tarafından SDK uygulaması açılırken aktarılan bilgilere ek olarak Hızlı Giriş’e ait olarak aşağıdaki bilgiler de aktarılmalıdır. Bu bilgiler kullanıcının Paycell ödeme sürecini hızlandıracaktır.
Üye İşyeri tarafından iletilen init parametrelerine mcParameters modeli eklenerek aşağıdaki gibi verilmelidir.  

Hızlı Giriş Parametreleri :
{
….
"mcParameters": {
"isMcSession": "Y"
"mcPhoneNumber": "5332109567",
"mcPhoneCountry": "90"
"mcAuthToken": "asdfalsdbfkajsdnlfkjasndlkjfnaldsk flkadsjnlkjadsnlvkjasdnlkjadsnlkjfnasdkjnasldkjfnaksdjnfkj"
}
…
}
 
Name Type M/O Description Example
isMobileConnectSession string Mandatory Bu alanda giriş yapan kullanıcı Hızlı Giriş ile girmiş ise true, girmemiş ise
false
verilir. true olduğunda alttaki 3 alanında iletilmesi beklenir.
true: Kullanıcı Hızlı Giriş ile girmiş ise false: Kullanıcı Hızlı Giriş ile girmemiş ise
MSISDN string Optional Hızlı Giriş’te kullanılmış telefon numarasıdır. 5332109567
countryCode string Optional Hızlı Giriş’te kullanılan telefon numarasının ülke kodu bilgisidir. 90, 1
accessToken string Optional Bu alanda Hızlı Giriş sisteminin vermiş olduğu authorization token bilgisi verilir. eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJwb3J0YWwiLCJpc3Mi OiJodHRwOlwvXC9sb2NhbGhvc3Q6ODA4MFwvbW9ia WxlY29ubmVjdFwvIiwiZXhwIjoxNTMyNDAyNDAzLCJpYX QiOjE1MzI0MDE4MDQsImp0aSI6ImEyMzJkOTdkLThjN WEtNDJiZi1hNzVkLTdmZGQ0ZGM4ZjkyZSJ9.ai0B1Fevk wYY35tuM_0O28lGtde2fjw9sbdnQJgbbNmZiRoNtkRjig-Gh9npfvliXTN48Zy8RDlbbTlnopsKlE1dVEhXITHvZzSXj9L 3WHaChWVI36lgXXsQREwzgZwzFZ9eD9Fg3xkvYdU986 JVB27YRO6y3GEMvyZhE_py2Qg

Validation Tracking

URL : https://websdktest.turkcell.com.tr/home/[trackingId]

Parametreler :
Name Type M/O Description Exemple
TrackingId string Mandatory Tracking bilgisi


TrackingId, ödemenin başlatıldığı init servisinin responsunda dönen, status servisinin o anki işlemi takip edebilmesi için gerekli olan uniq bir değerdir. Ödemenin durumu ve sonucu hakkında bilgi döndüren status servisinin request’ine parametre olarak TrackingId gönderilir.
Init isteği üzerinden elde ettiğimiz “TrackingId” bilgisi ile https://websdktest.turkcell.com.tr/home/[trackingId] sayfası, ilgili üye işyeri tarafından standart web sayfası, popup, iframe gibi HTML görüntüleyen araçlar üzerinden açılıp, Paycell Web SDK arayüz ekranlarına ulaşılır.

Timeout Kurgusu

postResultURL: Üye işyerinin vereceği adrese HttpPost işlemi yapılır.

Müşteri üye işyerinin verdiği zaman dahilinde işlemini bitirmezse yine üye işyerinin vereceği postResultURL adresine HttpPost işlemi yapılır.

Müşterini ödeme yapmasına rağmen timeout’a düşerse ( timeout süresinin bitmesine çok az bir zaman kala 3D ‘ye çıkıp ödemesini yapıp paycell tarafına geri döndüğünde eğer timeout ‘a düştüğü durumda) yapılan post işleminde yer alan model içerisindeki IsReverse alanına bakılarak Üye İşyeri tarafından iptal aksiyonu alınmalıdır.

Örnek Başarılı Durum ResponseModel

Name Type M/O Description Example
Message String Mandatory İşlem Mesajıdır Success
Result String Mandatory İşlem Sonuç Bilgisidir İşlem başarılı
StatusCode String Mandatory İşlem Sonuç Kodudur 0000
ResponseDateTime String Mandatory İşlem Sonuç Saatidir 21.3.2018 09:23:42
Amount String Mandatory Peşin fiyat bilgisi. Eğer farklı ödeme araçları için farklı fiyat kullanılmak istenirse ilgili ödeme aracı için installmentPlan değişkenine count=1 olarak bilgi eklenir. Bu değerin son iki hanesi kuruşu ifade eder.
  • 15.55 için 1555 iletilir.
  • 13.00 için 1300 iletilir.
PaymentReferenceNumber String Mandatory Üye işyeri tarafından SDK'ya iletilen bir ödeme isteğini tekil olarak ifade eden değerdir.
PaymentMethodType String Mandatory Ödeme yönteminin tipi dönülür.
  • CREDIT_CARD: Kredi Kartı ile yapılan ödemeler.
  • PCARD: Paycell Kart ile yapılan ödemeler.
  • DCB: Mobil Ödeme ile yapılan ödemeler.
  • EPARA: Dijital para ile yapılan ödemeler.
TrackingId String Mandatory Tracking bilgisi Servis Erişim Bigileri bölümünü inceleyebilirsiniz.
IsPaid Bool Mandatory Müşterinin timeout almasına rağmen ödeme yapıp yapmadığı bilgisini içerir True -> ödeme yaptı,
False -> ödeme yapmadı
IsTimeoutOperation Bool Mandatory Sepet süresinden dolayı timeout almış bir işlem için true, sepet süresi dolmamış işlemler için false döner. true->Üye İşyeri Sepet Süresi Dolmuş false-> Üye İşyeri Sepet Süresi Dolmamış
IsReverse Bool Mandatory Müşteri ödeme yapmasına rağmen eğer timeout almış olursa bu durumda Üye İşyeri’nin işlemi iptal etmesi gerekecektir. true -> Ödeme alınmıştır, bu işlem Üye İşyeri tarafından iptal edilmelidir.
false -> Ödeme alınmadığı için işlem iptalinde gerek yoktur.
IsCancelled Bool Mandatory Müşterinin İşYerine Dön butonu ile satın alma sürecini sonlandırıp Üye İşyeri ekranını açması durumunda true olarak iletilir, diğer durumlarda false olarak iletilir.


Örnek Hata Durum ResponseModel

Name Type M/O Description Example
Message String Mandatory İşlem Mesajıdır Success
Result String Mandatory İşlem Sonuç Bilgisidir İşlem başarılı
StatusCode String Mandatory İşlem Sonuç Kodudur 0000
ResponseDateTime String Mandatory İşlem Sonuç Saatidir 21.3.2018 09:23:42
Amount String Mandatory Peşin fiyat bilgisi. Eğer farklı ödeme araçları için farklı fiyat kullanılmak istenirse ilgili ödeme aracı için installmentPlan değişkenine count=1 olarak bilgi eklenir. Bu değerin son iki hanesi kuruşu ifade eder.
  • 15.55 için 1555 iletilir.
  • 13.00 için 1300 iletilir.
PaymentReferenceNumber String Mandatory Üye işyeri tarafından SDK'ya iletilen bir ödeme isteğini tekil olarak ifade eden değerdir.
PaymentMethodType String Mandatory Ödeme yönteminin tipi dönülür.
  • CREDIT_CARD: Kredi Kartı ile yapılan ödemeler.
  • PCARD: Paycell Kart ile yapılan ödemeler.
  • DCB: Mobil Ödeme ile yapılan ödemeler.
  • EPARA: Dijital para ile yapılan ödemeler.
TrackingId String Mandatory Tracking bilgisi Servis Erişim Bigileri bölümünü inceleyebilirsiniz.
IsPaid Bool Mandatory Müşterinin timeout almasına rağmen ödeme yapıp yapmadığı bilgisini içerir True -> ödeme yaptı,
False -> ödeme yapmadı
IsTimeoutOperation Bool Mandatory Sepet süresinden dolayı timeout almış bir işlem için true, sepet süresi dolmamış işlemler için false döner. true->Üye İşyeri Sepet Süresi Dolmuş false-> Üye İşyeri Sepet Süresi Dolmamış
IsReverse Bool Mandatory Müşteri ödeme yapmasına rağmen eğer timeout almış olursa bu durumda Üye İşyeri’nin işlemi iptal etmesi gerekecektir. true -> Ödeme alınmıştır, bu işlem Üye İşyeri tarafından iptal edilmelidir.
false -> Ödeme alınmadığı için işlem iptalinde gerek yoktur.
IsCancelled Bool Mandatory Müşterinin İşYerine Dön butonu ile satın alma sürecini sonlandırıp Üye İşyeri ekranını açması durumunda true olarak iletilir, diğer durumlarda false olarak iletilir.


Kullanıcının İşlemi İptal Etme Kurgusu

postResultURL: Üye işyerinin vereceği adrese HttpPost işlemi yapılır.

Müşteri ödemeyi yapmadan herhangi bir sebepten dolayı işlemi iptal etmek isteyip ekranda ki “İş Yerine Dön” butonuna bastığında, üye işyerinin vereceği postResultURL adresine HttpPost işlemi yapılır.

Response Model Header
Name Type M/O Description Example
Message String Mandatory İşlem Mesajıdır Success
Result String Mandatory İşlem Sonuç Bilgisidir İşlem başarılı
StatusCode String Mandatory İşlem Sonuç Kodudur 0000
ResponseDateTime String Mandatory İşlem Sonuç Saatidir 21.3.2018 09:23:42
Amount String Mandatory Peşin fiyat bilgisi. Eğer farklı ödeme araçları için farklı fiyat kullanılmak istenirse ilgili ödeme aracı için installmentPlan değişkenine count=1 olarak bilgi eklenir. Bu değerin son iki hanesi kuruşu ifade eder.
  • 15.55 için 1555 iletilir.
  • 13.00 için 1300 iletilir.
PaymentReferenceNumber String Mandatory Üye işyeri tarafından SDK'ya iletilen bir ödeme isteğini tekil olarak ifade eden değerdir.
PaymentMethodType String Mandatory Ödeme yönteminin tipi dönülür.
  • CREDIT_CARD: Kredi Kartı ile yapılan ödemeler.
  • PCARD: Paycell Kart ile yapılan ödemeler.
  • DCB: Mobil Ödeme ile yapılan ödemeler.
  • EPARA: Dijital para ile yapılan ödemeler.
TrackingId String Mandatory Tracking bilgisi Servis Erişim Bigileri bölümünü inceleyebilirsiniz.
IsPaid Bool Mandatory Müşterinin timeout almasına rağmen ödeme yapıp yapmadığı bilgisini içerir True -> ödeme yaptı,
False -> ödeme yapmadı
IsTimeoutOperation Bool Mandatory Sepet süresinden dolayı timeout almış bir işlem için true, sepet süresi dolmamış işlemler için false döner. true->Üye İşyeri Sepet Süresi Dolmuş false-> Üye İşyeri Sepet Süresi Dolmamış
IsReverse Bool Mandatory Müşteri ödeme yapmasına rağmen eğer timeout almış olursa bu durumda Üye İşyeri’nin işlemi iptal etmesi gerekecektir. true -> Ödeme alınmıştır, bu işlem Üye İşyeri tarafından iptal edilmelidir.
false -> Ödeme alınmadığı için işlem iptalinde gerek yoktur.
IsCancelled Bool Mandatory Müşterinin İşYerine Dön butonu ile satın alma sürecini sonlandırıp Üye İşyeri ekranını açması durumunda true olarak iletilir, diğer durumlarda false olarak iletilir.


postResultURL Adresine Ödeme İşlemi Sonrası İletilen Bilgiler

Müşteri ödemesini yaptıktan sonra üye işyerinin Init request içerisinde paycell servislerine ilettiği postResultURL adresine paycell tarafından HttpPost ile aşağıdaki model json olarak iletilir.

public class PaymentNotification
    {
        public string TrackingId { get; set; }
        public string PaymentMethodType { get; set; }
        public string PaymentReferenceNumber { get; set; }
        public bool IsPaid { get; set; }
        public bool IsReverse { get; set; }
        public string TransactionDate { get; set; }
        public string Amount { get; set; }
        public bool isTimeoutOperation { get; set; } 
                   public bool isCancelled { get; set; }
    }

Ortak Sınıflar

RequestHeader

Name Type M/O Description
merchant Merchant Mandatory Üye iş yeri bilgileri
transactionInfo TransactionInfo Mandatory İşlem bilgileri için Servis hata kodlarını inceleyebilirsiniz.
applicationName string Mandatory Üye işyeri application adı
applicationPassword string Mandatory Üye işyeri application şifresi

Merchant

Name Type M/O Description
merchantCode string Mandatory Üye işyeri kodu
terminalCode string Mandatory Üye işyeri terminal kodu
logos List Optional Üye işyeri logo listesi, url olarak eklenmelidir.

TransactionInfo

Name Type M/O Description
transactionDateTime string Mandatory Servis istek zamanı. yyyyMMddHHmmssSSS formatı kullanılır.
transactionId string Mandatory Servis isteğini tekil olarak belirten değer. Her servis isteğinde tekil olacak şekilde oluşturulmalıdır.Merchant’ın bu değeri bilmesine gerek yok.

Logo

Name Type M/O Description
name string Mandatory Logo adı.
url string Mandatory Logo url bilgisi.

Payment

Name Type M/O Description Example
amount string Mandatory Peşin fiyat bilgisi. Eğer farklı ödeme araçları için farklı fiyat kullanılmak istenirse ilgili ödeme aracı için installmentPlan değişkenine count=1 olarak bilgi eklenir. Bu değerin son iki hanesi kuruşu ifade eder.
  • 15.55 için 1555 iletilir.
  • 13.00 için 1300 iletilir.
currency string Mandatory Para birimi TL için 99 değeri iletilmelidir.
paymentReferenceNumber string Mandatory Üye işyeri tarafından SDK'ya iletilen bir ödeme isteğini tekil olarak ifade eden değerdir.
paymentSecurity string Mandatory Ödeme aracı olarak kredi kartı kullanılan ödemelerde ödeme güvenliğinin nasıl yapılacağını belirtir.
  • THREED_SECURE
  • NON_THREED_SECURE
installmentPlan List Optional Taksit planı listesi.


Validasyon Kuralları

Merchant’ın init request içerisinde Web SDK’ya ilettiği paymentReferenceNumber değeri max. 50 karakter olacak şekilde girilmelidir.
  • Msisdn, 10 karakterden ve yalnızca sayısal değerlerden oluşmalıdır.
  • Otp ve Pin, 4 karakterden ve yalnızca sayısal değerlerden oluşmalıdır.
  • Amex card 15, diğer kredi kartları ise 16 karakterden ve yalnızca sayısal değerlerden oluşmalıdır.

Installment Plan

API tarafına verilecek olan Taksit Seçenekleri parametreleri için aşağıdaki noktalara dikkat edilmeklidir.
  • Yeni bir taksit seçeneği eklerken “lineId”, 1’den başlayarak tekil olarak artmalıdır.
  • Her yeni bir seçenek için ayrı ayrı Card Brand ,Payment Method Type,Amount ve Count belirlenmelidir.
  • Her bir taksit seçeneği için ayrı taksit sayısı ve o taksit sayısında istenilecek tutar bilgilsi girilebilmektedir.
Name Type M/O Description Example
lineId string Mandatory Her satır için tekil olacak şekilde kullanılmalıdır. 1, 2, …
paymentMethodType string Mandatory Ödeme yöntemi tipi CreditCard, DCB
cardBrand string Optional Kart marka ortaklığı BONUS/WORLD/CARDFINANS/AXESS/ADVANTAGE/PARAF/MAXIMUM
count string Mandatory Taksit taksit adedi
amount string Mandatory İlgili taksit adedi için satış tutarı. Eğer farklı ödeme araçları için farklı fiyat kullanılmak istenirse ilgili ödeme aracı için installmentPlan değişkenine count=1 olarak bilgi eklenir. Bu değerin son iki hanesi kuruşu ifade eder.
  • 15.55 için 1555 iletilir.
  • 13.00 için 1300 iletilir.

Hash Hesaplama

hashData aşağıdaki gibi 2 aşamada oluşturulur.

  1. Security Data : Sha256(SecureCode + TerminalCode)
  2. Merchant Hash Data : Sha256(paymentReferenceNumber + terminalCode + amount + currency + paymentSecurity + hostAccount + installmentPlan (lineId sırası ile taksit bilgileri birleştirilir --> lineId + paymentMethodType + cardBrand + count + amount) + SecurityData)


  3. Güvenlik nedeniyle hashData sunucu tarafında oluşturulmalıdır.
    Her aşamada SHA256 Hash algoritması kullanılır. Her üye işyeri için MerchantCode, TeminalCode ve SecureCode oluşturulup üye işyeri ile paylaşılacaktır.

Paycell Mobil SDK Entegrasyon

Paycell IOS SDK dokümanını indirmek için tıklayınız.
Paycell Android SDK dokümanını indirmek için tıklayınız.

Paycell SDK RESTful Servis Bilgileri

Paycell SDK API’leri, üye işyerlerinin müşterilerine Paycell SDK ile sunduğu ödeme altyapısının iptal ve iade işlemlerini API ile sunulan web servis arayüzlerini sağlamaktadır.

İptal: Yapılan ödeme işleminin aynı gün iptal edilmesi amacıyla kullanılır.
İptal servisinden dönen kod 2029 ise iade servisi çağırılarak tutarın tamamının iade edilmesi şeklinde bir yol izlenmelidir. İptal servisi sadece aynı gün içerisinde yapılan işlemler için kullanılacağından, ertesi güne kalmış bir işlem için iade servisi çağrılmalıdır.

İade: Yapılan ödeme işleminin ertesi günden itibaren iptal edilmesi veya belirli bir tutarın iade edilmesi amacıyla kullanılır.

Statü Sorgulama: Üye İşyeri tarafından başlatılan işlemin ödeme statüsünü sorgulamak için kullanılır. Bunun için Üye İşyeri tarafından üretilmiş olan paymentRefenrence numarası ile sorgulama yapılması gerekmektedir.

İşlem Özeti:Üye İşyeri üzerinden yapılan işlemlerin satış, iptal ve iade durumları için belirtilen tarihte özetinin kontrolü yapılır.

İptal(Reverse) Servis Detayları

requestParameters

Feild Format Length (O)ptional/(M)andatory Description
originalPaymentReferenceNumber String 20 M İptal edilecek ödeme işlemine ait "paymentReferenceNumber" değeridir
referenceNumber String 20 M Üye işyeri uygulaması tarafından üretilecek unique numerik iptal işlemine ait referans numarası değeridir. İlk 3 hanesi uygulama bazında unique’dir, bu değer entegrasyon aşamasında Paycell tarafından bildirilecektir.
merchantCode String 19 M Ödeme işleminin başlatıldığı Paycell’de tanımlı üye işyeri kodu bilgisi gönderilir. Entegrasyon sonrasında her tanımlanan yeni üye işyeri için Paycell tarafından merchantCode değeri paylaşılır.
transactionId String 20 M applicationName bazında unique transactionId bilgisidir. Uygulama tarafından üretilir.
transactionDateTime String 17 M YYYYMMddHHmmssSSS formatında işlem zamanı bilgisidir
clientIPAddress String 50 M İşlemin başlatıldığı IP bilgisi
applicationName String 20 M Servisi çağıran uygulamaya özel belirlenmiş kullanıcı adı bilgisidir, entegrasyon aşamasında Paycell tarafından bildirilecektir
applicationPwd String 20 M Servisi çağıran uygulamaya özel belirlenmiş kullanıcı şifresi bilgisidir, entegrasyon aşamasında Paycell tarafından bildirilecektir


responseParameters

Feild Format Length (O)ptional/(M)andatory Description
reverseDetails Model O İşlemin mobil ödeme veya kredi kartı ile yapılma durumuna göre iptal işlemine ait detay bigilerini döner
paymentMethodType String 10 O creditCard
transactionId String 20 M requestHeader ile iletilen transactionId değeridir
responseDateTime String 17 M YYYYMMddHHmmssSSS formatında işlem cevabına ait işlem zamanı bilgisidir
responseCode String 20 M 0: Success, >0: Fail
responseDescription String 200 M Servis cevabı açıklaması


Model: paymentMethodType- creditCard

Feild Format Length (O)ptional/(M)andatory Description
approvalCode String 6 O Banka sisteminden iletilen onay kodudur
reconciliationDate String 8 O İşlemin mutabakatı için PAYCELL sisteminde belirlenen tarih bilgisidir. YYYYMMDD formatında olacaktır


Örnek Request

{
                "requestHeader": {
                                "transactionId": "14345678901234567890",
                                "transactionDateTime": "20160309112423230",
                                "clientIPAddress": "10.2252.187.81",
                                "applicationName": "ZUBIZU",
                                "applicationPwd": ****"
                                },
                                "merchantCode":"1183",
                                "msisdn":"905322108110",
                                "originalReferenceNumber":"T-33cfa1bc-1cd1-466a-8595-6b49ad4a9007",
                                "referenceNumber":"T-33cfa1bc-1cd1-466a-8595-6b49ad4a9008",
}


Örnek Response

{
                "responseHeader": {
                                "transactionId": "14345678901234567890",
                                "responseDateTime":"20180403091843451",
                                "responseCode":"0",
                                "responseDescription":"Success"
                                },
                                "reconciliationDate":"20180403",
                                "approvalCode":"910662"
}

İade(Refund) Servis Detayları

requestParameters

Feild Format Length (O)ptional/(M)andatory Description
originalPaymentReferenceNumber String 20 M İptal edilecek ödeme işlemine ait "paymentReferenceNumber" değeridir
referenceNumber String 20 M Üye işyeri uygulaması tarafından üretilecek unique numerik iptal işlemine ait referans numarası değeridir. İlk 3 hanesi uygulama bazında unique’dir, bu değer entegrasyon aşamasında Paycell tarafından bildirilecektir.
merchantCode String 19 M Ödeme işleminin başlatıldığı Paycell’de tanımlı üye işyeri kodu bilgisi gönderilir. Entegrasyon sonrasında her tanımlanan yeni üye işyeri için Paycell tarafından merchantCode değeri paylaşılır.
amount String 12 O İade edilmesi istenen işlem tutarıdır. Kısmi iade söz konusu ise iletilir. Son 2 hane KURUŞ'u ifade eder. Virgül kullanılmaz.
Örnekler:
1TL = 100
15,25TL = 1525
transactionId String 20 M applicationName bazında unique transactionId bilgisidir. Uygulama tarafından üretilir.
transactionDateTime String 17 M YYYYMMddHHmmssSSS formatında işlem zamanı bilgisidir
clientIPAddress String 50 M İşlemin başlatıldığı IP bilgisi
applicationName String 20 M Servisi çağıran uygulamaya özel belirlenmiş kullanıcı adı bilgisidir, entegrasyon aşamasında Paycell tarafından bildirilecektir
applicationPwd String 20 M Servisi çağıran uygulamaya özel belirlenmiş kullanıcı şifresi bilgisidir, entegrasyon aşamasında Paycell tarafından bildirilecektir


responseParameters

Feild Format Length (O)ptional/(M)andatory Description
refundDetails Model O İşlemin mobil ödeme veya kredi kartı ile yapılma durumuna göre iptal işlemine ait detay bigilerini döner
paymentMethodType String 10 O creditCard veya DCB
transactionId String 20 M requestHeader ile iletilen transactionId değeridir
responseDateTime String 17 M YYYYMMddHHmmssSSS formatında işlem cevabına ait işlem zamanı bilgisidir
responseCode String 20 M 0: Success, >0: Fail
responseDescription String 200 M Servis cevabı açıklaması


Model: paymentMethodType- creditCard

Feild Format Length (O)ptional/(M)andatory Description
approvalCode String 6 O Banka sisteminden iletilen onay kodudur
reconciliationDate String 8 O İşlemin mutabakatı için PAYCELL sisteminde belirlenen tarih bilgisidir. YYYYMMDD formatında olacaktır


Model: paymentMethodType- DCB

Feild Format Length (O)ptional/(M)andatory Description
requestTransactionId String 20 O
responseTransactionId String 20 O


Örnek Request

{
                               "requestHeader": {
                                "transactionId": "14345678901234567890",
                                "transactionDateTime": "20160309112423230",
                                "clientIPAddress": "10.2252.187.81",
                                "applicationName": "ZUBIZU",
                                "applicationPwd": ****"
                                },
                                "merchantCode":"1183",
                                "msisdn":"905322108110",
                                "originalReferenceNumber":"T-33cfa1bc-1cd1-466a-8595-6b49ad4a9007",
                                "referenceNumber":"T-33cfa1bc-1cd1-466a-8595-6b49ad4a9008",
                                "amount":"6"

}


Örnek Response

{
                                "responseHeader": {
                                "transactionId": "14345678901234567890",
                                "responseDateTime":"20180403091843451",
                                "responseCode":"0",
                                "responseDescription":"Success"
                                },
                                "reconciliationDate":"20180403",
                                "approvalCode":"910662"

}

Statü Sorgulama Servis Detayları

Statü Sorgulama Request Yapısı

Feild Format Length (O)ptional/(M)andatory Description
transactionId String 20 M applicationName bazında unique transactionId bilgisidir. Uygulama tarafından üretilir.
transactionDateTime String 17 M YYYYMMddHHmmssSSS formatında işlem zamanı bilgisidir.
clientIPAddress String 50 M İşlemin başlatıldığı IP bilgisi
applicationName String 20 M Servisi çağıran uygulamaya özel belirlenmiş kullanıcı adı bilgisidir, entegrasyon aşamasında Paycell tarafından bildirilecektir
applicationPwd String 20 M Servisi çağıran uygulamaya özel belirlenmiş kullanıcı şifresi bilgisidir, entegrasyon aşamasında Paycell tarafından bildirilecektir
originalPaymentReferenceNumber String 20 M Sorgulanmak istenen işleme ait "paymentReferenceNumber" değeridir.
merchantCode String 19 M Ödeme işleminin başlatıldığı Paycell’de tanımlı üye işyeri kodu bilgisi gönderilir. Entegrasyon sonrasında her tanımlanan yeni üye işyeri için Paycell tarafından merchantCode değeri paylaşılır.


Status Sorgulama Response Yapısı

Feild Format Length (O)ptional/(M)andatory Description
responseCode String 20 M İşlemin statü bilgisi verilir.
  • 0: başarılı statü sorgulama sonuçlarında dönülür.
  • !0: statü sorgulama sırasında hata alınırsa dönülür.
acquirerbankCode String 4 M Acquirer bank code bilgisi dönülür. Paycell Kart ve Kredi Kartı’ndan yapılan işlemler için dolu olacaktır.
MSISDN String 20 M Bu alanda işlem yapan MSISDN bilgisi dönülür.
amount String 8 M Bu alanda tutar bilgisi dönülür.
approvalCode String 19 M Bu alanda approval_code bilgisi dönülür.
currency String 3 M Bu alanda currency bilgisi dönülür.
installmentCount String 3 M Taksit sayısı dönülür.
  • Bu alanda 1 gelir is kullanıcı taksit seçmemiş demektir. 1’den fazla taksit bilgisi gelir ise müşteri taksitli işlem seçmiştir ve taksit bilgisi dönülmüş olur.
orderId String 50 M Order ID bilgisi dönülür.
paymentSecurity String 20 M İşlemin 3D secure olup olmadığı dönülür.
paymentDate String 20 M Bu alanda ödemenin gerçekleştiği tarih dönülür.
reconcilationDate String 20 M Mutabakat tarihi dönülür.
paymentReferenceNumber String 20 M Üye işyeri tarafından generate edilmiş original reference number bilgisi verilir. Statu sorgulama servisi requestindeki değerdir.
issuerBankCode String 4 M Issuer bank code bilgisi dönülür. Paycell Kart ve Kredi Kartı’ndan yapılan işlemler için dolu olacaktır.
merchantId String 4 M İşleme ait Sanal POS'un mağaza numara bilgisidir.
terminalId String 4 M İşleme ait Sanal POS'un terminalId bilgisidir.


Model: paymentResult

Feild Format Length (O)ptional/(M)andatory Description
status String 10 Bu alanda responsecode bilgisi verilir.
  • 0: Ödeme başarılı olan işlemler için döner.
  • 1: İptal olmuş işlemler için döner.
  • 2: İade olmuş işlemler için döner.
  • 3: İşlem bulunamamış ise bu şekilde dönülür.
  • 4: Bekleyen işlemler için dönülür.
  • 5: Bilinmeyen bir response alındığında dönülür.
  • 6: hata veya timeout durumları için dönülür.
statusExplanation String - Bu alanda hata durumları için status detayı dönülür.


Model: paymentMethod – Credit Card / Paycell Kart

Feild Format Length (O)ptional/(M)andatory Description
paymentMethodId String 20 Ödeme yöntemine ait unique bilgi dönülür.
paymentMethodNumber String 25 Maskeli kart numarası dönülür. CCPO servisi ile alınacaktır.
paymentMethodType String 15 Ödeme yönteminin tipi dönülür.
  • CREDIT_CARD: Kredi Kartı ile yapılan ödemeler.
  • PCARD: Paycell Kart ile yapılan ödemeler.


Model: paymentMethod – DCB / E-Para

Feild Format Length (O)ptional/(M)andatory Description
paymentMethodId String 20 Bu alanda telefon numarası dönülür.
paymentMethodNumber String 25 Bu alanda telefon numarası dönülür.
paymentMethodType String 15 Ödeme yönteminin tipi dönülür.
  • DCB: Mobil Ödeme ile yapılan ödemeler.
  • EPARA: Dijital para ile yapılan ödemeler.
Örnek Request

  {
                "originalPaymentReferenceNumber": "3fe058d9306e90ac",
                "merchantCode": "XXX",
                "requestHeader": {
                               "transactionId": "12345678901234567890",
                               "transactionDateTime": "20180604151749567",
                               "clientIPAddress": "127.0.0.01",
                               "applicationName": "APPLICATION",
                               "applicationPwd": "application"}
  }



Örnek Response

{
    "responseHeader": {
        "transactionId": "12345678901234567890",
       "responseDateTime": "20180721200626710",
        "responseCode": "0",
        "responseDescription": "Success"
    },
    "extraParameters": null,
    "acquirerbankCode": "046",
    "msisdn": "905356554665",
    "amount": 10000,
    "approvalCode": "312373",
    "currency": "99",
    "installmentCount": 1,
    "orderId": "225653584818071815002001",
    "paymentSecurity": "NON_THREED_SECURE",
    "paymentDate": "2018-07-18T15:00:20+03:00",
    "reconcilationDate": "20180718",
    "paymentReferenceNumber": "3fe058d9306e90ac",
    "issuerBankCode": "046",
    "status": "0",
    "statusExplanation": "Islem basarili",
    "paymentMethod": {
        "paymentMethodId": "886311",
        "paymentMethodNumber": "435508******4358",
        "paymentMethodType": "CREDITCARD"
    }
"merchantId": "100868773",
"terminalId": "100868773" 
}

İşlem Özeti Servis Detayları

Üye işyeri ve Paycell arasında işlem mutabakatı yapılması amacıyla kullanılır. Üye işyeri kendisinde gözüken işlem adet ve tutarlarını iletir, servis cevabında Paycell’deki adet ve tutarlar dönülür, eşit olması durumunda mutabakat durumu OK olarak dönülür.
Request Parameters
Field Format Length (O)ptional/(M)andatory Description
merchantCode String 19 O Ödeme işleminin başlatıldığı Paycell’de tanımlı üye işyeri kodu bilgisi gönderilir. Entegrasyon sonrasında her tanımlanan yeni üye işyeri için Paycell tarafından merchantCode değeri paylaşılır.
reconciliationDate String 8 M İşlemin mutabakatı için PAYCELL sisteminde belirlenen tarih. YYYYMMDD formatında olacaktır.
totalSaleAmount String 12 M İlgili tarihte gerçekleşen [Sale] işlemlerinin toplam tutarıdır. İşlem reverse edilmiş ise işleme ait sale kaydı reverse olarak güncellenir.
totalReverseAmount String 12 M İlgili tarihte gerçekleşen [Reverse] işlemlerinin toplam tutarıdır.
totalRefundAmount String 12 M İlgili tarihte gerçekleşen [Refund] işlemlerinin toplam tutarıdır.
totalPreAuthAmount String 12 M İlgili tarihte gerçekleşen [PreAuth] işlemlerinin toplam tutarıdır. İşlem reverse edilmiş ise işleme ait PreAuth kaydı PreAuth_reverse olarak güncellenir.
totalPostAuthAmount String 12 M İlgili tarihte gerçekleşen [PostAuth] işlemlerinin toplam tutarıdır. İşlem reverse edilmiş ise işleme ait PostAuth kaydı PostAuth_reverse olarak güncellenir.
totalPreAuthReverseAmount String 12 M İlgili tarihte gerçekleşen [PreAuth_Reverse] işlemlerinin toplam tutarıdır.
totalPostAuthReverseAmount String 12 M İlgili tarihte gerçekleşen [PostAuth_Reverse] işlemlerinin toplam tutarıdır.
totalSaleCount Number M İlgili tarihte gerçekleşen [Sale] işlemlerinin toplam adedidir. İşlem reverse edilmiş ise işleme ait sale kaydı reverse olarak güncellenir.
totalReverseCount Number M İlgili tarihte gerçekleşen [Reverse] işlemlerinin toplam adedidir.
totalRefundCount Number İlgili tarihte gerçekleşen [Refund] işlemlerinin toplam adedidir.
totalPreAuthCount Number İlgili tarihte gerçekleşen [PreAuth] işlemlerinin toplam adedidir. İşlem reverse edilmiş ise işleme ait PreAuth kaydı PreAuth_reverse olarak güncellenir.
totalPostAuthCount Number İlgili tarihte gerçekleşen [PostAuth] işlemlerinin toplam adedidir. İşlem reverse edilmiş ise işleme ait PostAuth kaydı PostAuth_reverse olarak güncellenir.
totalPreAuthReverseCount Number İlgili tarihte gerçekleşen [PreAuth_Reverse] işlemlerinin toplam adedidir.
totalPostAuthCount Number İlgili tarihte gerçekleşen [PostAuth_Reverse] işlemlerinin toplam adedidir.

Response Parameters
Field Format Length (O)ptional/(M)andatory Description
reconciliationResult String 10 M Mutabakat durumunu belirtir. OK, NOK
reconciliationDate String 8 M İşlemin mutabakatı için PAYCELL sisteminde belirlenen tarih. YYYYMMDD formatında olacaktır.
totalSaleAmount String 12 M Paycell üzerinde yer alan değerdir.
totalReverseAmount String 12 M Paycell üzerinde yer alan değerdir.
totalRefundAmount String 12 M Paycell üzerinde yer alan değerdir.
totalPreAuthAmount String 12 M Paycell üzerinde yer alan değerdir.
totalPostAuthAmount String 12 M Paycell üzerinde yer alan değerdir.
totalPreAuthReverseAmount String 12 M Paycell üzerinde yer alan değerdir.
totalPostAuthReverseAmount String 12 M Paycell üzerinde yer alan değerdir.
totalSaleCount Number M Paycell üzerinde yer alan değerdir.
totalReverseCount Number M Paycell üzerinde yer alan değerdir.
totalRefundCount Number M Paycell üzerinde yer alan değerdir.
totalPreAuthCount Number M Paycell üzerinde yer alan değerdir.
totalPostAuthCount Number M Paycell üzerinde yer alan değerdir.
totalPreAuthReverseCount Number M Paycell üzerinde yer alan değerdir.
totalPostAuthReverseCount Number M Paycell üzerinde yer alan değerdir.

Örnek Mutabakat İşlem Sayıları
100 tl’lik ve 120 tl’lik iki satış işlemi bulunmaktadır. Sırasıyla aşağıdaki işlemler yapılmıştır:
Case Mutabakat Sonucu
100 tl’lik (x) ve 120 tl’lik (y) olmak üzere iki satış işlemi bulunmaktadır TotalSaleAmount = 220
totalReverseAmount = 0
totalRefundAmount = 0
totalSaleCount = 2
totalReverseCount = 0
totalRefundCount = 0
100 tl’lik (x) işlem reverse yapılmıştır TotalSaleAmount = 120
totalReverseAmount = 100
totalRefundAmount = 0
totalSaleCount = 1
totalReverseCount = 1
totalRefundCount = 0
120 tl’lik (y) işlem için 50 tl’lik refund yapılmıştır TotalSaleAmount = 120
totalReverseAmount = 100
totalRefundAmount = 50
totalSaleCount = 1
totalReverseCount = 1
totalRefundCount = 1

Örnek Request
{
	"requestHeader": {
		"transactionId": "20190319120058671927",
		"transactionDateTime": "20190319120058671",
		"clientIPAddress": "10.252.187.81",
		"applicationName": "APPLICATION",
		"applicationPwd": "application"
	},
	"merchantCode": "xxx",
	"reconciliationDate": "20190308",
	"totalSaleAmount": "839817",
	"totalReverseAmount": "4989",
	"totalRefundAmount": "49815",
	"totalPreAuthAmount": "0",
	"totalPostAuthAmount": "0",
	"totalPostAuthReverseAmount": "0",
	"totalSaleCount": 82,
	"totalReverseCount": 2,
	"totalRefundCount": 13,
	"totalPreAuthCount": 0,
	"totalPostAuthCount": 0,
	"totalPreAuthReverseCount": 0,
	"totalPostAuthReverseCount": 0
} 

Örnek Response
{
    "responseHeader": {
        "transactionId": "20190319120058671927",
        "responseDateTime": "20190416154743792",
        "responseCode": "0",
        "responseDescription": "Success"
    },
    "reconciliationResult": "OK",
    "reconciliationDate": "20190308",
    "totalSaleAmount": "839817",
	"totalReverseAmount": "4989",
	"totalRefundAmount": "49815",
	"totalPreAuthAmount": "0",
	"totalPostAuthAmount": "0",
	"totalPostAuthReverseAmount": "0",
	"totalSaleCount": 82,
	"totalReverseCount": 2,
	"totalRefundCount": 13,
	"totalPreAuthCount": 0,
	"totalPostAuthCount": 0,
	"totalPreAuthReverseCount": 0,
	"totalPostAuthReverseCount": 0,
    "extraParameters": null
} 
 


Örnek Kodlar

Alttaki yönlendirme ve hazır kodlar paycell entegrasyonunda size yardımcı olmayı hedeflemektedir.
Yönlendirmeler ile yapının nasıl işlediğini görebilir, hazır kodlar kısmındaki fonksiyon ve modeller ile entegrasyon sürenizi kısaltabilirsiniz. Kısa sürede paycell dünyasında sizleri de görmek istiyoruz.

                 

Test Kredi Kartları

Entegrasyon sürecinde kullanabileceğiniz test kredi kartlarını aşağıda görebilirsiniz.

BANKA Test Kart No AY YIL CVC 3D Şifresi
Akbank 4355084355084358 12 26 000 a
Akbank 5571135571135575 12 26 000 a
Yapı Kredi 4506347011448053 02 20 000 Şifresiz
Yapı Kredi 4506347022052795 02 20 000 Şifresiz
Yapı Kredi 4506347031187533 02 20 000 Şifresiz
Yapı Kredi 4506347043358536 02 20 000 Şifresiz
Yapı Kredi 4921307045825277 02 20 000 Şifresiz
Yapı Kredi 5400610093155852 02 20 000 Şifresiz
Yapı Kredi 5400617049774124 02 20 000 Şifresiz
Yapı Kredi 5400637003737156 02 20 000 Şifresiz
Yapı Kredi Debit 4943141483711580 07 21 576 Şifresiz
FinansBank 4022774022774026 12 19 000 a
FinansBank 5456165456165454 12 19 000 a
Garanti Bankası 4282209027132016 05 20 165
Garanti Bankası Amex 375622005485014 10 20 123 Şifresiz
Garanti Bankası 4824894728063019 07 23 172
Garanti Bankası 4282209004348015 08 22 123 Şifresiz
İş Bankası 4508034508034509 12 19 000 a
İş Bankası 5406675406675403 12 19 000 a
Vakıfbank 4938410114062912 01 20 956 GS1905vb03
Vakıfbank 4029400184884303 01 23 376 Şifresiz
HalkBank 4531444531442283 12 19 001 a
HalkBank 5818775818772285 12 19 001 a
HSBC Bankası 4282405990002166 01 20 000 a
HSBC Visa 4282405990002166 12 20 000 a
HSBC Master 5254135922971748 12 20 000 a
International Master 5105105105105100 12 19 000 a
International Visa 4716081467305766 12 19 000 a
Denizbank 4090700090840057 11 22 592 123
Denizbank 4090700101174272 12 22 104 123
Paycell Card 4622760000066950 12 19 932 Şifresiz
TEB Troy 9792230099127843 11 21 787 123456
İş Bankası (Troy Credit) 9792042022562362 10 25 000 123456
Ziraat Bankası 4546711234567894 12 26 000 a
Ziraat Bankası 5401341234567891 12 26 000 a
Vakıfbank 4289450189088488 04 23 060 12ABCDEF
Vakıfbank 4289450187923330 04 23 813 12ABCDEF
ING Bank 4508034508034509 12 26 000 a
ING Bank 5406675406675403 12 26 000 a