iyzico ile Ödeme Entegrasyonuna Genel Bakış

Published in

Kod Gemisi

6 min readOct 15, 2018

Merhaba bu yazımda iyzico ödeme sistemiyle entegrasyon yaparken genel olarak dikkat edilmesi gereken konulara değineceğim.

Başlarken şunu belirteyim; iyzico API dokümanı ben implementasyonu gerçekleştirirken 2 tane vardı. 2 tane diyorum çünkü dokümanların İngilizce olanı ve Türkçe olanı içerik ve kapsam bakımından birbirlerinden farklıydılar. Bu oldukça sinir bozucu bir durumdu :-$

Burada referans aldığım belgeleri şöyle bırakayım:

Türkçe Doküman İçin : https://dev.iyzipay.com/tr
İngilizce Doküman İçin : https://dev.iyzipay.com/en

Bir de ben implementasyon yaparken şöyle bir döküman yayınlandı ama benim inceleme şansım olmadı : https://iyzico.gitbook.io/tr

Sisteme şu adresten kaydoluyoruz. Kayıt işlemini gerçekleştirdikten sonra “Ayarlar” menüsünden API Anahtarı ve Güvenlik Anahtarı bilgilerine ulaşabilirsiniz.

Entegrasyon yaparken desteklenen diller için şu Github adresinde API clientları bulunuyor.

Biz java clientını kullanacağımız için onun da linki burada.

iyzico API’sine Genel Bakış

Ödemeyi iyzico API’si üzerinden hazır sundukları checkout formu başlatma ve payment requesti ile yapabiliyoruz. O halde ilk önce checkout formu başlatma requesti ve implementasyonuna başlayalım.

Checkout (Ödeme) Formu Başlatma

iyzico API dokümanında Checkout Form başlatmayla ilgili avantajlardan şu şekilde bahsediliyor:

Ön yüz kontrolleri, BIN sorgulama, Taksit Sorgulama, 3D Secure ile ödeme, BKM Express ve Kart saklama entegrasyonları için ek sorgu yapmaya gerek kalmadan tek bir entegrasyon ile işlemler tamamlanır. Ödeme bazında 3D Secure ayarı ve taksit komisyon yönetimi iyzico kontrol panelinden kolayca düzenlenebilir. Üye iş yeri tasarımına göre pop-up veya responsive olarak yüklenebilir. iframe ve ortak ödeme sayfası olarak kullanım şekilleri mevcuttur. İki basit aşamadan oluşur…

Checkout Form ile alakalı edindiğim deneyimler sonucunda aktarmak istediğim kilit noktalar ise şu şekilde :

iyzico Checkout Form’unda kredi kartı bilgilerini dolduran müşterilerin kredi kartı bilgilerini saklamak istersek iyzico üzerinden bu özelliği aktifleştirmemiz gerek. Test modunda çalışırken de bu özelliğin açılmış olması gerekiyor.
iyzico Checkout Form’unda kredi kartı saklama özelliği açıkken bu forma bir checkbox ekleniyor ve burada “Bu kartı sakla” yazıyor. Bu checkbox işaretliyse bilgileri saklayabiliyoruz.

Müşteri ödeme bilgilerini girdikten sonra iyzico’dan bize bir token dönüyor ve bu token ile ödemenin sonucuna ulaşabiliyoruz.

BIN (Bank Identification Number) ve Taksit Sorgulama

Bu API Endpoint’ine iyzico checkout formunu kullanıyorsanız ihtiyacınız olacağını düşünmüyorum.

Söz konusu endpoint;

Taksit sorgulama (installment),
İlgili kart bir kredi kartı ise ve bir taksit programına dahil ise, kaç taksit yapılabileceği ile taksit komisyon oranı,
Taksit komisyon oranı

konularında bilgi vermektedir.

Bu endpointe binNumber, locale, conversationId ve price bilgilerini gönderip kart ile bilgilere ulaşabiliyoruz. Garip bir şekilde sadece price parametresi zorunlu :-|, sadece price bilgisini gönderirsek bütün taksit seçenekleri dönüyor.

Bu endpoint ile binNumber gönderip kartın tipini öğrenebiliriz, dönen DEBIT_CARD ya da CREDIT_CARD sonucuna göre de kartla ilgili ödemenin threeDs yapılıp yapılmayacağına karar verebiliriz. Bir de kart tiplerine ek olarak bu endpointten dönen force3ds parametresi “1” olarak dönerse ödeme threeDs olarak yapılmalıdır.

Bu endpointlere ek olarak İade, İptal ve BKM Express ile Ödeme endpointleri de bulunuyor. Bunlarla ilgili bilgiye bağlantılardan ulaşabilirsiniz.

Kendi Checkout Formumuzu Tasarlamak İstersek …

iyzico’nun checkout formunun isterlerimizi karşılamadığı bazı durumlarda ya da farklı checkout formu tasarımları kullanmak istediğimizde kullanmamız gereken endpointler şu şekilde olacak :

BIN ve Taksit Sorgulama : Bu endpoint ile kullanıcının girdiği kart bilgilerine göre taksit seçeneklerini, yapılacak olan ödemenin 3D olup olmayacağını, hangi kartlara ne kadar taksit imkanı olduğu gibi kararları kullanmak için bu endpointi kullanırız.
Ödeme : Bu endpoint ile müşterinin kartından ödeme işlemi gerçekleştirilir ve bunun sonucunda işlemin başarılı olup olmadığının yanıtı döner.
3D ile Ödeme : Bu endpoint ile 3D ödeme işlemlerini yapabiliyoruz. Bu işlem 2 aşamadan oluşur; öncelikle 3D ile ödeme başlatılır, bunun sonucunda müşterimiz banka ile SMS onayını sağlar ve bize bazı parametreler yollanır, bu parametler ile ödemenin sonucuna ulaşırız.

Kendi formumuzu tasarlamaya başladıktan sonra kabaca uygulamamız gereken işlemleri müşterinin kredi kartı bilgilerini girebileceği bir ekran tasarımı, bu esnada kredi kartı numarasının validasyonu, CVC kodu validasyonu, ilgili kartın taksit imkanları olarak sıralayabiliriz. (Şu aşamada bahsettiğim validasyonlar aslında UI’da olan validasyonlar.)

Müşterimiz kredi kartı numarasını ve CVC kodunu doldurduğunda, kredi kartı numarası ile ödeme işleminin 3D ile olup olmayacağının kontrolü sonucunda işleme devam etmemiz gerekiyor. Bu sorguları BIN ve Taksit Sorgulama endpointi ile sağlayabiliriz. Bu endpointten sonraki adımı belirlememiz için dokümanda yazan şu satırlar bize referans olacaktır:

card_type parametresi DEBIT_CARD olarak döndüğünde bu kart ile yapılmak istenen ödeme işlemi 3D ile ödeme kullanılarak yapılmalıdır.
force3ds(installmentDetails) değeri 1 olarak döner ise, işlem 3D olarak yapılmalıdır. 0 ise işlem 3D olmadan yapılabilir; ek olarak 3D de tercih edilebilir. Üye işyerine 3D zorunlu olarak işaretlenmiş ise bu değer sürekli 1 olarak döner.

Bu arada, “iyzico Türk bankalarına ait posları kulanmaktadır ve bu bankalar, Türk kartından bir işlem döviz olarak gelirse “Türk Lirasını Koruma Kanunu” gereği reddetmektedir.” ifadesinde yer alan konuyla alakalı olarak; dolar ya da diğer para birimleriyle ödeme alıyorsak ödeme işlemi yapımızı tekrar gözden geçirmemiz gerekmektedir.

Ödeme işlemini gerçekleştiren sorgumuzu yaparken eğer daha sonra müşteriden belirli aralıklarda yeniden ödeme almamız gerekirse (recurring payment yani abonelik söz konusu ise)setRegisterCard parametresini 1 olarak set ediyoruz. (3D ile ödeme ve 3D’siz ödeme işlemlerinde bu işlem aynı) Ödeme işleminin sonucunda bize iyzico’dan cardToken ve cardUserKey fieldları dönecek, bu bilgiler ile daha sonra ödeme işlemi sağlayabileceğiz.

Ödeme Endpointi

Bu endpoint ile iyzico tarafından istenilen parametrelerle ödeme işlemi sağlanıyor.

Ödeme adımında kabaca gereken parametreler; faturalandırma bilgileri, satın alma bilgileri, kredi kartı bilgileri ve sepette bulunan ürünler.

Ödeme isteği requestini gönderdikten sonra sonuç olarak bize success ya da failure olarak bir status değeri dönüyor. failure statusünde bize sadece errorCode, errorMessage, errorGroup parametreleri dönüyor.

Bu durumlara ek olarak değinmek istediğim bir diğer konu da şu; ödeme işlemi gerçekleştirirken iyzico bize fraud status parametresi ile ödemenin fraud olup olmama durumu ile bilgiler dönmektedir. Bu durumların ayrıntılarını şu şekilde inceleyebiliriz:

Ödeme işleminin fraud filtrelerine göre durumu: Eğer ödemenin fraud risk skoru düşük ise ödemeye anında onay verilir, bu durumda 1 değeri döner. Eğer fraud risk skoru yüksek ise ödeme işlemi reddedilir ve -1 döner. Eğer ödeme işlemi daha sonradan incelenip karar verilecekse 0 döner. Geçerli değerler: 0, -1 ve 1. Üye işyeri sadece 1 olan işlemlerde ürünü kargoya vermelidir, 0 olan işlemler için bilgilendirme beklemelidir.

Burda bizim için aslında 0 olarak dönen responselar önemli hale gelmiş oluyor çünkü henüz ödeme için bir tanım koyulmamış durumda, yani ödeme bizim için success ya da failure değil PENDING durumunda; bu durumdaki ödemeler için 2 şekilde çözüm sağlayabiliriz:

iyzico panelinde bir web-hook tanımlıyoruz ve iyzico bu işlem için bize bir request atıyor, biz de bunun sonucunda ödemenin success ya da failure olduğunu anlamış oluyoruz.
Bu yöntemde ise ilgili paymentId yi saklayıp biz iyzico’ya fraud kontrolünün sonucunu soruyoruz.

İlgili paymentı şu şekilde getirebiliriz :

RetrievePaymentRequest request = new RetrievePaymentRequest();
request.setPaymentId(paymentId);
request.setLocale(Locale.EN.name());
Payment.retrieve(request, options);

3D ile Ödeme Endpointini Kullanma

3D Ödeme sorgusu müşterilerinizin bankamatik kartlarından ve kredi kartından para çekme işlemini yapar. Bu servis iki aşamadan oluşmaktadır.

Şimdi süreç halinde inceleyecek olursak BIN ile sorgulama yaptıktan sonra 3D ödeme olup olmayacağının kararını verdik. Bir önceki incelediğimiz ödeme endpointi ile gönderdiğimiz parametreler aynı, sadece bu ödeme bizim için 3 aşamalı olduğu için bir callback URL’i de göndermemiz gerekiyor.

3D payment sorgumuzu yaptık ve bize sonuç olarak status( status failure ise errorCode, errorGroup, errorMessage gelecek, diğer durumlarda ise bu değerler null olacak), systemTime, conversationId ve htmlContent parametreleri geldi. Bu aşamada dönen htmlContent’i müşteriye göstermemiz gerekiyor, müşteri bu aşamada bankadan gelen SMS kodunu girecek ve bizim set ettiğimiz callback URL’ine aşağıdaki değerler post edilecek:

status, paymentId, conversationData, conversationId, mdStatus

Bu adım, üye işyeri, iyzico ve banka üçlüsü arasında el sıkışma(handshake) için gereklidir. Bu aşamada henüz para çekilmemiştir. 3D Secure modellerinde 3D modeli tam doğrulama(Full 3DS) ile kullanılmaktadır. Eğer başarılı bir şekilde dönüş adresinizde paymentId ve conversationData (geldiyse) değerlerini alabildiyseniz, işlemi ödemeye çevirme sorgusunu yapabilirsiniz.

Bu parametreler geldikten sonra ödemeyi artık alabiliriz. Bunu da şu şekilde sağlıyoruz:

(conversationData boşssa göndermemize gerek yok)

CreateThreedsPaymentRequest request = new CreateThreedsPaymentRequest();
request.setPaymentId(paymentId);
request.setConversationId(conversationId);
request.setLocale(Locale.EN.name());
request.setConversationData(conversationData);

return ThreedsPayment.create(request, options);

bunun sonucunda elimizde ThreedsPayment objesi olacak ve dönen parametreler ödeme endpointinde dönen parametreler ile aynı.

Kaydedilmiş Kredi Kartı ile Ödeme Yapmak İçin …

Ödeme ya da 3D ile ödeme endpointinde setRegisterCard parametresini 1 olarak set ettik ve istek sonucunda bize iyzico tarafından cardToken ve cardUserKey bilgileri döndü bunları sakladık, şimdi nasıl bunlarla birlikte ödeme yapacağız ?

CreatePaymentRequest request = new CreatePaymentRequest();

şeklide objemizi oluşturduk, gerekli parametreler ile doldurduk. Önceki sorgularda şu şekilde yapıyorduk :

PaymentCard paymentCard = new PaymentCard();paymentCard.setCardHolderName(cardHolderName);
paymentCard.setCardNumber(creditCardNumber);
paymentCard.setExpireMonth(expireMonth);
paymentCard.setExpireYear(expireYear);
paymentCard.setCvc(cvc);
paymentCard.setRegisterCard(1);request.setPaymentCard(paymentCard);

artık kart bilgilerini set etmeyeceğiz, onu da şu şekilde yapabiliriz:

PaymentCard paymentCard = new PaymentCard();paymentCard.setCardUserKey(cardUserKey);
paymentCard.setCardToken(userCardToken);request.setPaymentCard(paymentCard);

Hatırlatma : Kart bilgilerini saklayabilmek için iyzico üzerinden bu özelliğin açılması gerekiyor.(Test ortamında da dahil olmak üzere)

Kaydedilmiş kart ile ödeme işlemlerimizi bu şekilde sağlayabiliyoruz.

Genel olarak entegrasyon hakkında ön plana çıkan konularda bahsetmek istediklerim bu kadar.