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://sdk-services-test.turkcell.com.tr/api/Session/Init
https://sdk-services-test.turkcell.com.tr/Validation/Tracking/[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://sdk-services-test.turkcell.com.tr/api/Session/Init )
  • Init servisi cevabında işlem başarılı olursa trackingID üretilir.
  • TrackingID bilgisi kullanılarak https://sdk-services-test.turkcell.com.tr/Validation/Tracking/[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://sdk-services-test.turkcell.com.tr/api/Session/Init
 
NameTypeM/ODescription
requestHeaderRequestHeaderMandatoryÜye iş yeri, ve işlem bilgileri Paycell Web SDK Nedir? kısmını inceleyebilirsiniz
hashDatastringMandatoryBununla ilgili Paycell Entegrasyon kısmını inceleyebilirsiniz.
hostAccountstringMandatoryÜ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.
languagestringMandatoryDil bilgisi. tr/en
paymentPaymentMandatoryOrtak Sınıflar başlığını inceleyebilirsiniz.
returnUrlstringMandatoryReturnUrl, ö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. 
postResultUrlstringMandatoryBu 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.
timeoutDurationstringMandatoryÜ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"
}
…
}
 
NameTypeM/ODescriptionExample
isMobileConnectSessionstringMandatoryBu 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ş isefalse: Kullanıcı Hızlı Giriş ile girmemiş ise
MSISDNstringOptionalHızlı Giriş’te kullanılmış telefon numarasıdır.5332109567
countryCodestringOptionalHızlı Giriş’te kullanılan telefon numarasının ülke kodu bilgisidir.90, 1
accessTokenstringOptionalBu alanda Hızlı Giriş sisteminin vermiş olduğu authorization token bilgisi verilir.eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJwb3J0YWwiLCJpc3MiOiJodHRwOlwvXC9sb2NhbGhvc3Q6ODA4MFwvbW9iaWxlY29ubmVjdFwvIiwiZXhwIjoxNTMyNDAyNDAzLCJpYXQiOjE1MzI0MDE4MDQsImp0aSI6ImEyMzJkOTdkLThjNWEtNDJiZi1hNzVkLTdmZGQ0ZGM4ZjkyZSJ9.ai0B1FevkwYY35tuM_0O28lGtde2fjw9sbdnQJgbbNmZiRoNtkRjig-Gh9npfvliXTN48Zy8RDlbbTlnopsKlE1dVEhXITHvZzSXj9L3WHaChWVI36lgXXsQREwzgZwzFZ9eD9Fg3xkvYdU986JVB27YRO6y3GEMvyZhE_py2Qg

Validation Tracking

URL : https://sdk-services-test.turkcell.com.tr/Validation/Tracking/[trackingId]

Parametreler :
Name Type M/ODescription Exemple
TrackingIdstringMandatoryTracking 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://sdk-services-test.turkcell.com.tr/Validation/Tracking/[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/ODescription Example
MessageStringMandatoryİşlem MesajıdırSuccess
ResultStringMandatoryİşlem Sonuç Bilgisidirİşlem başarılı
StatusCodeStringMandatoryİşlem Sonuç Kodudur0000
ResponseDateTimeStringMandatoryİşlem Sonuç Saatidir21.3.2018 09:23:42
AmountStringMandatoryPeş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.
PaymentReferenceNumberStringMandatoryÜye işyeri tarafından SDK'ya iletilen bir ödeme isteğini tekil olarak ifade eden değerdir.
PaymentMethodTypeStringMandatoryÖ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.
TrackingIdStringMandatoryTracking bilgisiServis Erişim Bigileri bölümünü inceleyebilirsiniz.
IsPaidBoolMandatoryMüşterinin timeout almasına rağmen ödeme yapıp yapmadığı bilgisini içerirTrue -> ödeme yaptı,
False -> ödeme yapmadı
IsTimeoutOperationBoolMandatorySepet 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ış
IsReverseBoolMandatoryMüş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.
IsCancelledBoolMandatoryMüş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/ODescription Example
MessageStringMandatoryİşlem MesajıdırSuccess
ResultStringMandatoryİşlem Sonuç Bilgisidirİşlem başarılı
StatusCodeStringMandatoryİşlem Sonuç Kodudur0000
ResponseDateTimeStringMandatoryİşlem Sonuç Saatidir21.3.2018 09:23:42
AmountStringMandatoryPeş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.
PaymentReferenceNumberStringMandatoryÜye işyeri tarafından SDK'ya iletilen bir ödeme isteğini tekil olarak ifade eden değerdir.
PaymentMethodTypeStringMandatoryÖ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.
TrackingIdStringMandatoryTracking bilgisiServis Erişim Bigileri bölümünü inceleyebilirsiniz.
IsPaidBoolMandatoryMüşterinin timeout almasına rağmen ödeme yapıp yapmadığı bilgisini içerirTrue -> ödeme yaptı,
False -> ödeme yapmadı
IsTimeoutOperationBoolMandatorySepet 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ış
IsReverseBoolMandatoryMüş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.
IsCancelledBoolMandatoryMüş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/ODescription Example
MessageStringMandatoryİşlem MesajıdırSuccess
ResultStringMandatoryİşlem Sonuç Bilgisidirİşlem başarılı
StatusCodeStringMandatoryİşlem Sonuç Kodudur0000
ResponseDateTimeStringMandatoryİşlem Sonuç Saatidir21.3.2018 09:23:42
AmountStringMandatoryPeş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.
PaymentReferenceNumberStringMandatoryÜye işyeri tarafından SDK'ya iletilen bir ödeme isteğini tekil olarak ifade eden değerdir.
PaymentMethodTypeStringMandatoryÖ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.
TrackingIdStringMandatoryTracking bilgisiServis Erişim Bigileri bölümünü inceleyebilirsiniz.
IsPaidBoolMandatoryMüşterinin timeout almasına rağmen ödeme yapıp yapmadığı bilgisini içerirTrue -> ödeme yaptı,
False -> ödeme yapmadı
IsTimeoutOperationBoolMandatorySepet 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ış
IsReverseBoolMandatoryMüş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.
IsCancelledBoolMandatoryMüş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 PaymnetReferenceNumber { get; set; }
        public bool IsPaid { get; set; }
        public bool IsReverse { get; set; }
        public string TrnsactionDate { get; set; }
        public string Amount { get; set; }
        public bool isTimeoutOperation { get; set; } 
                   public bool isCancelled { get; set; }
    }

Ortak Sınıflar

RequestHeader

NameTypeM/ODescription
merchantMerchantMandatoryÜye iş yeri bilgileri
transactionInfoTransactionInfoMandatoryİşlem bilgileri için Servis hata kodlarını inceleyebilirsiniz.
applicationNamestringMandatoryÜye işyeri application adı
applicationPasswordstringMandatoryÜye işyeri application şifresi

Merchant

NameTypeM/ODescription
merchantCodestringMandatoryÜye işyeri kodu
terminalCodestringMandatoryÜye işyeri terminal kodu
logosListOptionalÜye işyeri logo listesi, url olarak eklenmelidir.

TransactionInfo

NameTypeM/ODescription
transactionDateTimestringMandatoryServis istek zamanı. yyyyMMddHHmmssSSS formatı kullanılır.
transactionIdstringMandatoryServis 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

NameTypeM/ODescription
namestringMandatoryLogo adı.
urlstringMandatoryLogo url bilgisi.

Payment

NameTypeM/ODescriptionExample
amountstringMandatoryPeş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.
currencystringMandatoryPara birimiTL için 99 değeri iletilmelidir.
paymentReferenceNumberstringMandatoryÜye işyeri tarafından SDK'ya iletilen bir ödeme isteğini tekil olarak ifade eden değerdir.
paymentSecuritystringMandatoryÖdeme aracı olarak kredi kartı kullanılan ödemelerde ödeme güvenliğinin nasıl yapılacağını belirtir.
  • THREED_SECURE
  • NON_THREED_SECURE
installmentPlanListOptionalTaksit 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.
NameTypeM/ODescriptionExample
lineIdstringMandatoryHer satır için tekil olacak şekilde kullanılmalıdır.1, 2, …
paymentMethodTypestringMandatoryÖdeme yöntemi tipiCreditCard, DCB
cardBrandstringOptionalKart marka ortaklığıBONUS/WORLD/CARDFINANS/AXESS/ADVANTAGE/PARAF/MAXIMUM
countstringMandatoryTaksit taksit adedi
amountstringMandatoryİ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 + intallmentPlan (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
originalPaymentReferenceNumberString20Mİptal edilecek ödeme işlemine ait "paymentReferenceNumber" değeridir
referenceNumberString20MÜ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.
merchantCodeString19MÖ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.
transactionIdString20MapplicationName bazında unique transactionId bilgisidir. Uygulama tarafından üretilir.
transactionDateTimeString17MYYYYMMddHHmmssSSS formatında işlem zamanı bilgisidir
clientIPAddressString50Mİşlemin başlatıldığı IP bilgisi
applicationNameString20MServisi çağıran uygulamaya özel belirlenmiş kullanıcı adı bilgisidir, entegrasyon aşamasında Paycell tarafından bildirilecektir
applicationPwdString20MServisi çağıran uygulamaya özel belirlenmiş kullanıcı şifresi bilgisidir, entegrasyon aşamasında Paycell tarafından bildirilecektir


responseParameters

Feild Format Length(O)ptional/(M)andatoryDescription
reverseDetailsModelOİşlemin mobil ödeme veya kredi kartı ile yapılma durumuna göre iptal işlemine ait detay bigilerini döner
paymentMethodTypeString10OcreditCard
transactionIdString20MrequestHeader ile iletilen transactionId değeridir
responseDateTimeString17MYYYYMMddHHmmssSSS formatında işlem cevabına ait işlem zamanı bilgisidir
responseCodeString20M0: Success, >0: Fail
responseDescriptionString200MServis cevabı açıklaması


Model: paymentMethodType- creditCard

Feild Format Length(O)ptional/(M)andatoryDescription
approvalCodeString6OBanka sisteminden iletilen onay kodudur
reconciliationDateString8 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
originalPaymentReferenceNumberString20Mİptal edilecek ödeme işlemine ait "paymentReferenceNumber" değeridir
referenceNumberString20MÜ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.
merchantCodeString19MÖ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.
amountString12Oİ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
transactionIdString20MapplicationName bazında unique transactionId bilgisidir. Uygulama tarafından üretilir.
transactionDateTimeString17MYYYYMMddHHmmssSSS formatında işlem zamanı bilgisidir
clientIPAddressString50Mİşlemin başlatıldığı IP bilgisi
applicationNameString20MServisi çağıran uygulamaya özel belirlenmiş kullanıcı adı bilgisidir, entegrasyon aşamasında Paycell tarafından bildirilecektir
applicationPwdString20MServisi çağıran uygulamaya özel belirlenmiş kullanıcı şifresi bilgisidir, entegrasyon aşamasında Paycell tarafından bildirilecektir


responseParameters

Feild Format Length(O)ptional/(M)andatoryDescription
refundDetailsModelOİşlemin mobil ödeme veya kredi kartı ile yapılma durumuna göre iptal işlemine ait detay bigilerini döner
paymentMethodTypeString10OcreditCard veya DCB
transactionIdString20MrequestHeader ile iletilen transactionId değeridir
responseDateTimeString17MYYYYMMddHHmmssSSS formatında işlem cevabına ait işlem zamanı bilgisidir
responseCodeString20M0: Success, >0: Fail
responseDescriptionString200MServis cevabı açıklaması


Model: paymentMethodType- creditCard

Feild Format Length(O)ptional/(M)andatoryDescription
approvalCodeString6OBanka sisteminden iletilen onay kodudur
reconciliationDateString8 Oİşlemin mutabakatı için PAYCELL sisteminde belirlenen tarih bilgisidir. YYYYMMDD formatında olacaktır


Model: paymentMethodType- DCB

Feild Format Length(O)ptional/(M)andatoryDescription
requestTransactionIdString20O
responseTransactionIdString20 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
transactionIdString20MapplicationName bazında unique transactionId bilgisidir. Uygulama tarafından üretilir.
transactionDateTimeString17MYYYYMMddHHmmssSSS formatında işlem zamanı bilgisidir.
clientIPAddressString50Mİşlemin başlatıldığı IP bilgisi
applicationNameString20MServisi çağıran uygulamaya özel belirlenmiş kullanıcı adı bilgisidir, entegrasyon aşamasında Paycell tarafından bildirilecektir
applicationPwdString20MServisi çağıran uygulamaya özel belirlenmiş kullanıcı şifresi bilgisidir, entegrasyon aşamasında Paycell tarafından bildirilecektir
originalPaymentReferenceNumberString20MSorgulanmak istenen işleme ait "paymentReferenceNumber" değeridir.
merchantCodeString19MÖ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
responseCodeString20Mİş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.
acquirerbankCodeString4MAcquirer bank code bilgisi dönülür. Paycell Kart ve Kredi Kartı’ndan yapılan işlemler için dolu olacaktır.
MSISDNString20MBu alanda işlem yapan MSISDN bilgisi dönülür.
amountString8MBu alanda tutar bilgisi dönülür.
approvalCodeString19MBu alanda approval_code bilgisi dönülür.
currencyString3MBu alanda currency bilgisi dönülür.
installmentCountString3MTaksit 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.
orderIdString50MOrder ID bilgisi dönülür.
paymentSecurityString20Mİşlemin 3D secure olup olmadığı dönülür.
paymentDateString20MBu alanda ödemenin gerçekleştiği tarih dönülür.
reconcilationDateString20MMutabakat tarihi dönülür.
paymentReferenceNumberString20MÜye işyeri tarafından generate edilmiş original reference number bilgisi verilir. Statu sorgulama servisi requestindeki değerdir.
issuerBankCodeString4MIssuer bank code bilgisi dönülür. Paycell Kart ve Kredi Kartı’ndan yapılan işlemler için dolu olacaktır.
merchantIdString4Mİşleme ait Sanal POS'un mağaza numara bilgisidir.
terminalIdString4Mİşleme ait Sanal POS'un terminalId bilgisidir.


Model: paymentResult

Feild Format Length(O)ptional/(M)andatory Description
statusString10Bu 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.
statusExplanationString-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
paymentMethodIdString20Ödeme yöntemine ait unique bilgi dönülür.
paymentMethodNumberString25Maskeli kart numarası dönülür. CCPO servisi ile alınacaktır.
paymentMethodTypeString15Ö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
paymentMethodIdString20Bu alanda telefon numarası dönülür.
paymentMethodNumberString25Bu alanda telefon numarası dönülür.
paymentMethodTypeString15Ö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
FieldFormatLength(O)ptional/(M)andatoryDescription
merchantCodeString19OÖ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.
reconciliationDateString8Mİşlemin mutabakatı için PAYCELL sisteminde belirlenen tarih. YYYYMMDD formatında olacaktır.
totalSaleAmountString12Mİ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.
totalReverseAmountString12Mİlgili tarihte gerçekleşen [Reverse] işlemlerinin toplam tutarıdır.
totalRefundAmountString12Mİlgili tarihte gerçekleşen [Refund] işlemlerinin toplam tutarıdır.
totalPreAuthAmountString12Mİ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.
totalPostAuthAmountString12Mİ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.
totalPreAuthReverseAmountString12Mİlgili tarihte gerçekleşen [PreAuth_Reverse] işlemlerinin toplam tutarıdır.
totalPostAuthReverseAmountString12Mİlgili tarihte gerçekleşen [PostAuth_Reverse] işlemlerinin toplam tutarıdır.
totalSaleCountNumberMİlgili tarihte gerçekleşen [Sale] işlemlerinin toplam adedidir. İşlem reverse edilmiş ise işleme ait sale kaydı reverse olarak güncellenir.
totalReverseCountNumberMİlgili tarihte gerçekleşen [Reverse] işlemlerinin toplam adedidir.
totalRefundCountNumberİlgili tarihte gerçekleşen [Refund] işlemlerinin toplam adedidir.
totalPreAuthCountNumberİlgili tarihte gerçekleşen [PreAuth] işlemlerinin toplam adedidir. İşlem reverse edilmiş ise işleme ait PreAuth kaydı PreAuth_reverse olarak güncellenir.
totalPostAuthCountNumberİlgili tarihte gerçekleşen [PostAuth] işlemlerinin toplam adedidir. İşlem reverse edilmiş ise işleme ait PostAuth kaydı PostAuth_reverse olarak güncellenir.
totalPreAuthReverseCountNumberİlgili tarihte gerçekleşen [PreAuth_Reverse] işlemlerinin toplam adedidir.
totalPostAuthCountNumberİlgili tarihte gerçekleşen [PostAuth_Reverse] işlemlerinin toplam adedidir.

Response Parameters
FieldFormatLength(O)ptional/(M)andatoryDescription
reconciliationResultString10MMutabakat durumunu belirtir. OK, NOK
reconciliationDateString8Mİşlemin mutabakatı için PAYCELL sisteminde belirlenen tarih. YYYYMMDD formatında olacaktır.
totalSaleAmountString12MPaycell üzerinde yer alan değerdir.
totalReverseAmountString12MPaycell üzerinde yer alan değerdir.
totalRefundAmountString12MPaycell üzerinde yer alan değerdir.
totalPreAuthAmountString12MPaycell üzerinde yer alan değerdir.
totalPostAuthAmountString12MPaycell üzerinde yer alan değerdir.
totalPreAuthReverseAmountString12MPaycell üzerinde yer alan değerdir.
totalPostAuthReverseAmountString12MPaycell üzerinde yer alan değerdir.
totalSaleCountNumberMPaycell üzerinde yer alan değerdir.
totalReverseCountNumberMPaycell üzerinde yer alan değerdir.
totalRefundCountNumberMPaycell üzerinde yer alan değerdir.
totalPreAuthCountNumberMPaycell üzerinde yer alan değerdir.
totalPostAuthCountNumberMPaycell üzerinde yer alan değerdir.
totalPreAuthReverseCountNumberMPaycell üzerinde yer alan değerdir.
totalPostAuthReverseCountNumberMPaycell ü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:
CaseMutabakat Sonucu
100 tl’lik (x) ve 120 tl’lik (y) olmak üzere iki satış işlemi bulunmaktadırTotalSaleAmount = 220
totalReverseAmount = 0
totalRefundAmount = 0
totalSaleCount = 2
totalReverseCount = 0
totalRefundCount = 0
100 tl’lik (x) işlem reverse yapılmıştırTotalSaleAmount = 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ırTotalSaleAmount = 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.

BANKATest Kart NoAYYILCVC3D Şifresi
Akbank43550843550843581226000a
Akbank55711355711355751226000a
Yapı Kredi45063470114480530220000Şifresiz
Yapı Kredi45063470220527950220000Şifresiz
Yapı Kredi45063470311875330220000Şifresiz
Yapı Kredi45063470433585360220000Şifresiz
Yapı Kredi49213070458252770220000Şifresiz
Yapı Kredi54006100931558520220000Şifresiz
Yapı Kredi54006170497741240220000Şifresiz
Yapı Kredi54006370037371560220000Şifresiz
Yapı Kredi Debit49431414837115800721576Şifresiz
FinansBank40227740227740261219000a
FinansBank54561654561654541219000a
Garanti Bankası42822090271320160520165
Garanti Bankası Amex3756220054850141020123Şifresiz
Garanti Bankası48248947280630190723172
Garanti Bankası42822090043480150822123Şifresiz
İş Bankası45080345080345091219000a
İş Bankası54066754066754031219000a
Vakıfbank49384101140629120120956GS1905vb03
Vakıfbank40294001848843030123376Şifresiz
HalkBank45314445314422831219001a
HalkBank58187758187722851219001a
HSBC Bankası42824059900021660120000a
HSBC Visa42824059900021661220000a
HSBC Master52541359229717481220000a
International Master51051051051051001219000a
International Visa47160814673057661219000a
Denizbank40907000908400571122592123
Denizbank40907001011742721222104123
Paycell Card46227600000669501219932Şifresiz
TEB Troy97922300991278431121787123456
İş Bankası (Troy Credit)97920420225623621025000123456
Ziraat Bankası45467112345678941226000a
Ziraat Bankası54013412345678911226000a
Vakıfbank4289450189088488042306012ABCDEF
Vakıfbank4289450187923330042381312ABCDEF
ING Bank45080345080345091226000a
ING Bank54066754066754031226000a