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

RequestHeader

Merchant

TransactionInfo

Logo

Payment

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

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

Örnek Hata Durum ResponseModel

Test Ortamı URL : https://websdktest.turkcell.com.tr/home/[trackingId]
Prod Ortamı URL : https://paycellsdk.paycell.com.tr/home/[trackingId]

Parametreler :

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

Parametreler :
Test Ortamı URL : https://websdktest.turkcell.com.tr/api/session/init
Prod Ortamı URL : https://paycellsdk.paycell.com.tr/api/session/init

Ö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

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

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

Status Sorgulama Response Yapısı

Model: paymentResult

Model: paymentMethod – Credit Card / Paycell Kart

Model: paymentMethod – DCB / E-Para

Örnek Request

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

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

responseParameters

Model: paymentMethodType- creditCard

Model: paymentMethodType- DCB

Ö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

responseParameters

Model: paymentMethodType- creditCard

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

Test Ortamı Servis Bilgileri

Prod Ortamı 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.

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.