×
Paycell Ucretsiz - Uygulama Marketlerde
İNCELE

Paycell SDK

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

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)
    1. Güvenlik nedeniyle hashData sunucu tarafında oluşturulmalıdır.
    1. 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.

 

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.

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.

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 paid { get; set; }
        public bool reverse { get; set; }
        public string transactionDate { get; set; }
        public string amount { get; set; }
        public bool timeoutOperation { get; set; } 
        public bool cancelled { get; set; }
        public bool giftMoneyUsage { get; set; }
	public string usedGiftMoneyAmount { get; set; }
    }

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: Ü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.

Test Ortamı URL : https://websdktest.turkcell.com.tr/home/[trackingId]
Prod Ortamı URL : https://paycellsdk.paycell.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.

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ş isefalse: 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.eyJhdWQiOiJwb3J0YWwiLCJpc3MiOiJodHRwOlwvXC9sb2NhbGhvc3Q6ODA4MFwvbW9iaWxlY29ubmVjdFwvIiwiZXhwIjoxNTMyNDAyNDAzLCJpYXQiOjE1MzI0MDE4MDQsImp0aSI6ImEyMzJkOTdkLThjNWEtNDJiZi1hNzVkLTdmZGQ0ZGM4ZjkyZSJ9.ai0B1FevkwYY35tuM_0O28lGtde2fjw9sbdnQJgbbNmZiRoNtkRjig-Gh9npfvliXTN48Zy8RDlbbTlnopsKlE1dVEhXITHvZzSXj9L3WHaChWVI36lgXXsQREwzgZwzFZ9eD9Fg3xkvYdU986JVB27YRO6y3GEMvyZhE_py2Qg

Parametreler :
Test Ortamı URL : https://websdktest.turkcell.com.tr/api/session/init
Prod Ortamı URL : https://paycellsdk.paycell.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"
}

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.

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.

Ü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.

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

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. 1TL için x100 olacak şekilde 100 olarak 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.
refundedAmount String 8 M İşleme ait iade yapılan tutar bilgisidir. 1TL için x100 olacak şekilde 100 olarak dönülür. Parçalı iade işlemlerinde amount alanı ile refundedAmount alanı eşit olmayacaktır. İade gerçekleşmemiş bir işlem için 0 dönülür.

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",
	"refundedAmount": 0,
    "paymentMethod": {
        "paymentMethodId": "886311",
        "paymentMethodNumber": "435508******4358",
        "paymentMethodType": "CREDITCARD"
    }
"merchantId": "100868773",
"terminalId": "100868773" 
}

 

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"

}

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

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.

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.

                 

Entegrasyon sürecinde kullanabileceğiniz test kredi kartlarını https://paycell.com.tr/test-kredi-kartlari sayfasında görebilirsiniz.