Genel Bilgiler

iPara ödeme, cüzdan ve diğer servisler, dünya standartlarına uygun yapıda ve tüm yazılımlarla entegre olarak çalışabilecek şekilde oturum bilgisi tutmayan (stateless) Restful servis odaklı bir mimaride geliştirilmiştir. Yine bu rehbere eşlik edecek örnek projeler sayesinde iPara servislerine çok daha kolay entegre olabilirsiniz.

Başlarken

iPara servislerine, servis yapılarına göre XML veya JSON formatında veri göndererek ve alarak hızlıca entegre olabilirsiniz. Yaptığınız işlemlerin sonuçlarını iPara kurumsal panelinden rahatlıkla takip edebilirsiniz.

Yine bu rehber sayesinde entegrasyon adımlarını, istediğiniz yazılım dilinde kolayca gerçekleştirebileceksiniz. iPara github hesabı üzerinden bu örnek projelere erişebildiğiniz gibi burada da ilgili kod parçalarını görebileceksiniz. iPara servislerini kullanabilmek için bir kurum hesabı oluşturmanız gereklidir.

iPara entegrasyon için, tüm yazılım dilleriyle entegre olabilir yapıları sunar. Bunun yanında bu rehber boyunca aşağıdaki dillerde örnek kodlara ve github üzerinden örnek projelere de ulaşarak hızlıca entegrasyon sağlayabilirsiniz.

Entegrasyon sürecinde dikkat edilecek noktalar

Canlı ortamda iPara'nın apilerine gönderilen parametrelere müşteriden alınan bilgiler ilgili alanlara koyularak gönderilmelidir. Canlı ortamda hiç bir şekilde sabit, dummy değerler ilgili servislere gönderilmemelidir. Örnek projelerde yer alan örnek değerler sizin konuyu daha kolay anlamanıza yardımcı olmak amacıyla vardır. Müşteri, ürün, miktar gibi bilgilerin tümü müşterilerizin beyan ettiği veya veritabanınızdan gelecek değerler olmalıdır. Bu sahteciliği önlemek adına çok önemlidir. Entegrasyon sonrası, test işlemlerinde gönderilen parametreler iPara kurum panelinizdeki sipariş arama sayfası üzerinden mutlaka kontrol edilmeli ve doğru gönderildiğinden emin olunmalıdır.

Önemli Notlar

  • Servisleri kullanabilmek için iPara kurum başvuru aşamalarını tamamlamış olmanız gerekmektedir. Başvuru adımlarını tamamladıktan sonra kurum panelinizden alabileceğiniz public ve private key bilgileri ile servisleri kullanabilirsiniz.
  • Entegrasyon işlemlerinde encoding “UTF-8” kullanılması gerekmektedir. Özellikle token parametresinden kaynaklı alınan hataların büyük çoğunluğu encoding problemlerinden kaynaklanmaktadır. Ek olarak XML dili için olan özel karakterlerin gönderiminde hata almamak için yine encoding yapılması gerekmektedir.
  • Servis isteği yaparaken göndermiş olduğunuz alanların başında ve sonunda oluşabilecek boşluk alanlarını kaldırmanızı ( trim() ) önemle rica ederiz. Çünkü bu alanlar oluşacak hash sonuçlarını etkilemektedir.
  • Entegrasyon dahilinde gönderilen input alanlarında, kart numarası alanı dışında kart numarası bilgisi gönderilmesi halinde işlem reddedilecektir.

İstek Modu

iPara bir kere canlıya geçtikten sonra test geliştirmelerine devam edebilmeniz için her servis çağrısında o çağrının test ortamda mı yoksa canlı ortam için mi yapıldığını sağlamak adına bu bilgiyi sizden bir parametre olarak ister.

Test modu gerçek kart bilgisi kullanmaya gerek kalmadan test ödemeleri yapmanızı sağlayan bir ödeme modudur. Bu sayede SMS ile 3D secure doğrulaması yapmadan testlerinizi hızlıca yapabilirsiniz. Ayrıca test ödemelerinde gerçek bir banka posu kullanılmadığından, ödeme gerçek kart bilgileri ile yapıldığında bile test kartlarından para çekilmeyecektir. Test modunda ödeme yapabilmek için ödeme isteklerinizde mode parametresini "T" olarak yollamanız gerekmektedir. iPara panelinizdeki "Sipariş Arama" sayfasında sağ alttaki "Test Ödemeleri" tercihi ile arama yaptığınız zaman test ödemelerinizi görebilirsiniz. Test işlemlerinizi bitirdikten sonra gerçek ödeme tahsilatı için mode parametresini "P" olarak yollamanız gerekmektedir.

Hash (token) Hesaplama

iPara’nın size sunduğu tüm servislerin güvenliğini sağlamak işlemin sizin tarafınızdan gönderildiğini ve cevabın iPara tarafından size gönderildiği karşılıklı olarak doğrulamak için oluşturduğu bir yöntem hash bilgisinin karşılıklı olarak iletilmesidir. Hash bilgisinin üretilebilmesi için çeşitli veriler birleştirilir ve bu birleştirilen verilerin sonucunda yapılan bir işlemle kısa bir "string" oluşturulur. Bu bilgiyi alan tarafta aynı hash verisini oluşturursa aradaki iletişimin güvenli olduğuna karar verilir ve işlemlere devam edilir.

Hash fonksiyonu aşağıdaki şekilde oluşturulur ve çağrılır:

hashString: Her serviste deklare edilen ve her servise özgü, değişen verilerin yanyana birleştirilmesi sonucu ortaya çıkan değer (String Concatate)
PublicKey: Mağaza Açık Anahtarınız
Hash: PublicKey:Base64(SHA1(HashString))

Bir zincir halinde birleştirilerek oluşturulan hashString verisi önce SHA-1 algoritması ile hashlenir ve ardından Base64 formatına çevrilir. Daha sonra mağaza açık anahtarı ile birlikte arada iki nokta (:) olacak şekilde birleştirilir ve ilgili alanda gönderilir.

Veri Örneği: token = “ASKJH98675ASDASDPO:jhsa/gd+89dfg0df6SA/dfg8967==

*Mağaza Açık Anahtarı
*HashString’in önce SHA1 algoritmasından geçirilmiş ve ardından Base64 formatına çevrilmiş hali.

Hash Hesaplama Aracı

Bu araç sayesinde verilerinizi birbirine ekleyerek anında hash(token) oluşturabilirsiniz, böylece kendi entegrasyonunuzda oluşturduğunuz token bilgisini karşılaştırabilirsiniz.

Canlı ortama geçiş

  • Test ortamında kullandığınız statik verilerin canlı ortamda gerçek müşteri datasıyla değiştirildiğinden emin olun.
  • Canlı ortamda yanlış, sabit data gönderilmediğinden emin olun. Gönderdiğiniz işlemlere ait verileri mutlaka size özel panelden görüntüleyin.
  • Geliştirmeler tamamlandıktan sonra ödeme adımlarını, iPara test kartları ile tüm olası durumlar için test edin ve sonuçlarını görüntüleyin.
  • iPara servislerinden dönen ve olabilecek tüm hataları karşılayacak ve müşteriye uygun cevabı gösterecek şekilde kodunuzu düzenleyin ve test edin. iPara hata kodları kullanıcı dostu mesajlar olup müşterinize gösterebilirsiniz.
  • Hassas olmayan verileri ve servis yanıtlarını, hata çözümü ve olası sorunların çözümünde yardımcı olması açısından loglamaya dikkat edin.
  • Canlı ortama geçiş sonrası ilk işlemleri kendi kredi kartlarınız ile deneyerek sonuçlarını size özel Kurum ekranlarından görüntüleyin. Sonuçların ve işlemlerin doğru tamamlandığından emin olun.

Örnek Projeler ve Projelerin Kullanımı




İlgili örnek projeleri daha rahat kavrayabilmek adına mimariyi ve birkaç öneriyi sizinle paylaşmak isteriz:
  • Örnek Projeler olabildiğince OOP (Object Oriented Programming) dizaynına uygun olarak tasarlanmıştır.
  • İstek sınıfları ve cevap sınıfları ayrı ayrı yazılmıştır.
  • Ayarlar (Settings) sınıfı tüm servislerde kullanılan parametrelerin ortak bir yerde barındırılması amacıyla tasarlanmıştır.
  • Helper sınıfı bir çok ortak metodu barındırır. Her yerde aynı fonksiyonları çağırmak yerine bu sınıfın metotlarını kullanabilirsiniz.