Subscription

iyzico subscription API, online ödeme alabilen üye işyerlerine hızlıca abonelik oluşturma imkanı sağlar. Kart saklama, ödeme takibi gibi ekstra kaynak ve development gerektiren sürece girmeden tekrarlı ödemeler alınabilir. Eğer iş modeliniz tekrarlı ödeme almaya uygunsa örneğin premium, gold üyelik sunan bir servis sağlayıcısı, spor salonu hizmetleri, dergi aboneliği vs. subscription API size hızlı ve güvenilir bir çözüm sunar.

Abonelik sistemi temelde 3 aşamadan oluşur.

1. ÜRÜN
2. PLAN
3. ABONELİK

Örneğin yayınladığınız 2 farklı dergi için abonelik süreci başlatmak isterseniz, A dergisi ve B dergisi olarak iki ürün oluşturmanız, dergilerin basım zamanına göre ödeme planı oluşturmanız yeterlidir. A dergisinin her ay, B dergisinin her hafta basıldığını varsayarsak, A dergisine ait plan aylık 50 TL, B dergisine ait plan haftalık 30 TL olarak belirlenebilir. iyzico her plan için size bir referans kodu verir. Bir ödeme isteğinde bu referans kodunu göndermeniz, son kullanıcıyı o plana abone yapmak için yeterlidir.

Ürün ve planlar iyzico merchant panelinden veya API istekleri ile saniyeler içinde oluşturulabilir, güncellenebilir veya silinebilir. Aboneliği başlatmak için API üzerinden bir ödeme isteği gönderilmelidir. Ödeme, checkout form veya direk API isteği ile gerçekleştirilebilir.

Bu sayfada subscription API temel bilgileri anlatılmaktadır. Detaylı API dökümantasyonu linkten indirilebilir. Destek için entegrasyon@iyzico.com adresine yazabilirsiniz.

NOT: Abonelik çözümü sadece kredi kartları ile kullanılabilmektedir.

1- ÜRÜN

Subscription API ödeme planlarına göre tekrarlı ödeme alır ve her ödeme planı en az bir ürüne bağlıdır. Ürün sayısında herhangi bir sınırlama yoktur ve sadece isim bilgisi gönderilerek bir ürün oluşturulabilir.

iyzico merchant panelinden veya API üzerinden aşağıdaki işlemler gerçekleştirilebilir.

Servise gönderilmesi gereken parametreler şu şekildedir:

Parametre İsmi Tip Zorunlu Açıklama
locale String Hayır iyzico istek sonucunda dönen metinlerin dilini ayarlamak için kullanılır. Varsayılan değeri tr’dir. en olarak kullanılabilir.
conversationId String Hayır İstek esnasında gönderip, sonuçta alabileceğiniz bir değer, request/response eşleşmesi yapmak için kullanılabilir. En yaygın kullanış biçimi üye iş yerinin ürün numarasıdır.
name String Evet Ürün adı. Eşsiz bir isim olmalıdır. Mevcut bir isim başka bir ürüne verilemez
Description String Hayır Ürün açıklaması. Bu açıklama müşterilere gösterilebilir veya tarafınızda bir not olabilir

Servisten dönen parametreler şu şekildedir:

Parametre İsmi Tip Açıklama
status String Yapılan isteğin sonucunu belirtir. İşlem başarılı ise success değeri döner
systemTime Long Dönen sonucun o anki unix timestamp değeridir.
referenceCode String Oluşturulan ürüne ait eşsiz referans kodu. Ürün güncellemek veya silmek, ürün detayı görmek ve plan oluşturmak için kullanılır.
createdDate Long Ürün oluşturulma tarihi
name String Ürün adı. İstek sırasında ürüne verdiğiniz isimdir.
description String Ürün açıklaması. İstek anında gönderilmiş ise cevapta bu bilgi geri iletilir.
pricingPlans Array Ürün'e bağlı planları gösterir. Ürün oluşturulduğu anda henüz bir plan olmadığı için boş gelmektedir

Ürün güncelleme, ürün silme, ürün detayı getirme ve ürün listeleme servisleri ayrıntılı dökümantasyonda gösterilmektedir.

2- PLAN

Ödeme planı müşterilerinizin hangi tutarda, hangi aralıkta ve ne kadar süre ödeme yapacağını belirler. Bir ürüne dilediğiniz kadar farklı fiyat ve ödeme sıklığında ödeme planı ekleyebilirsiniz.

iyzico merchant panelinden veya API üzerinden aşağıdaki işlemler gerçekleştirilebilir.

Servise gönderilmesi gereken parametreler şu şekildedir:

Parametre İsmi Tip Zorunlu Açıklama
locale String Hayır iyzico istek sonucunda dönen metinlerin dilini ayarlamak için kullanılır. Varsayılan değeri tr’dir. en olarak kullanılabilir.
conversationId String Hayır İstek esnasında gönderip, sonuçta alabileceğiniz bir değer, request/response eşleşmesi yapmak için kullanılabilir. En yaygın kullanış biçimi üye iş yerinin plan numarasıdır.
productReferenceCode String Evet Planın ilişkilendirileceği ürünün referans kodu.
name String Evet Plan adı. Ödeme planı ile ilgili kısa bir bilgilendirme olacak şekilde değer girilmelidir.
price Decimal Evet Ödeme periyotlarında karttan çekilecek tutar. Plan için geçerli abonelik fiyatı.
currencyCode String Evet Ödemenin alınacağı para birimi. TL, USD, EUR olabilir. TL dışındaki para birimlerinin hesabınıza tanımlandığından emin olunuz.
paymentInterval String Evet Tekrarlı ödemenin alınacağı periodu belirler. DAILY,WEEKLY,MONTHLY,YEARLY değerlerini alabilir.
paymentIntervalCount Integer Evet Ödeme periodunun hangi sıklıkta olacağını belirler. Örneğin paymentInterval değeri WEEKLY, paymentIntervalCount değeri 2 olursa, ödemeler 2 hafta bir alınır
trialPeriodDays Integer Hayır Deneme süresi veya ücretsiz kullanım süresi olarak kullanılır. Bu değer girilirse, ilk ödeme girilen gün sayısı sonunda alınır.
planPaymentType String Evet Abonelik tipini belirtir. RECURRING değeri girilmelidir.
recurrenceCount Integer Hayır Ödeme periyodunun kaç kez tekrarlanacağını belirler. Örneğin ayda bir ödeme alan planınıza bu değeri 12 olarak girerseniz, 12 ay boyunca ödeme alınacaktır.

Servisten dönen parametreler şu şekildedir:

Parametre İsmi Tip Açıklama
status String Yapılan isteğin sonucunu belirtir. İşlem başarılı ise success değeri döner
systemTime Long Dönen sonucun o anki unix timestamp değeridir.
referenceCode String Oluşturulan plana ait eşsiz referans kodud. Plan güncellemek veya silmek, plan detayını görmek, abonelik başlatmak için kullanılır.
createdDate Long Plan oluşturulma tarihi
name String Plan adı. İstek sırasında plana verdiğiniz isimdir.
productReferenceCode String Plana bağlı ürünün referans kodu. İstekte gönderdiğiniz ürün bilgisi geri iletilir.
price String İstekte gönderdiğiniz değer geri iletilir. Ödeme periyotlarında karttan çekilecek tutardır.
currencyCode String İstekte gönderdiğiniz değer geri iletilir. Ödemenin alınacağı para birimi.
paymentInterval String İstekte gönderdiğiniz değer geri iletilir. Tekrarlı ödemenin alınacağı periodu belirler.
paymentIntervalCount Integer İstekte gönderdiğiniz değer geri iletilir. Ödeme periodunun hangi sıklıkta olacağını belirler.
trialPeriodDays Integer İstekte gönderdiğiniz değer geri iletilir. Bu değer gönderilmediyse 0 olarak döner.
planPaymentType String RECURRING değerini döner ve ödemenin tekrarlı olduğunu belirtir.
recurrenceCount Integer İstekte gönderdiğiniz değer geri iletilir. Ödeme periyodunun kaç kez tekrarlanacağını belirler
status(data) String Planın durumunu gösterir. ACTIVE değerini alır.

Plan güncelleme, ürün silme, ürün detayı getirme ve ürün listeleme servisleri ayrıntılı dökümantasyonda paylaşılmıştır.

3- ABONELİK

Genel hatlarıyla abonelik süreci

  • Müşterilerinizden günlük, haftalık, aylık veya yıllık tekrarlayan ödemeler alabilirsiniz.
  • Aboneliğe konu olacak ürünün ya da hizmetin adı, açıklaması, fiyatı, tekrarlı ödeme sıklığı gibi parametreler hem iyzico kontrol paneli hem de API üzerinden ayarlanabilmektedir.
  • iyzico'nun POS ürünü gibi hem API ile hem de check-out form ile ödeme alma imkanı vardır.
  • Kredi kartı saklama ile ilgili tüm süreç ve gereksinimlerin karşılanması iyzico tarafındadır. Kolay ödeme formu ile müşterinin girdiği kart bilgisi iyzico tarafında güvenle saklanarak tekrarlayan ödemeler bu karttan tahsil edilir.
  • Tekrarlayan ödemeler iyzico tarafından günü geldiğinde müşterinizin kayıtlı kredi kartından tahsil edilir. Başarılı ve başarısız tahsilat işlemlerini kontrol panelinizden ve API üzerinden sorgulayabilirsiniz. Başarısız ödemelerin tekrar tetiklenmesini API ya da panel üzerinden yapabilirsiniz.
  • Ödeme planınıza opsiyonel olarak ekleyebileceğiniz "Otomatik abonelik sonlandırma" ile müşterinizin aboneliği önceden belirlediğiniz tekrarlı ödeme sayısına ulaşınca abonelik otomatik olarak sonlanır.
  • Her bir ödeme planı için deneme süresi tanımlayabilirsiniz. Kredi kartı bilgisi deneme süresi başlangıcında, yani ilk aşamada kaydedildiği için Abonelik, tanımladığınız deneme süresi sonunda tahsilatı otomatik yapılarak başlatılacaktır.
  • Müşterilerinizin aboneliğini dilediğiniz bir anda API veya panel üzerinden iptal edebilirsiniz. İptal edilen abonelikler için bir sonraki ve takip eden dönemlerde hiç bir tahsilat yapılmaz.
  • Abonelik yalnızca kredi kartına yapılabilmektedir, debit kartlar kabul edilmemektedir.
  • Web-hook yöntemi ile sizin vereceğiniz bir endpoint'e her tahsilat denemesinin sonucu hakkında bilgilendirme isteği gönderilebilir.

ABONELİK BAŞLATMA

CHECKOUT FORM OLUŞTURULLMASI

Bu sayfada yalnızca checkout form ile abonelik oluşturma bilgisi verilmiştir. Direk API ile abonelik oluşturmak için dökümanı inceleyebilir veya destek ekibimizle(entegrasyon@iyzico.com) iletişime geçebilirsiniz

iyzico'nun standart ödemelerde sunduğu checkout form çözümü, abonelik için benzer yapıda kullanılabililir

Checkout form oluşturulması için gerekli bilgiler şunlardır:

  • Plan referans kodu
  • Müşteri bilgisi
  • Abonelik durumu
  • CallBack adresi

Servise gönderilmesi gereken parametreler şu şekildedir:

Parametre ismi Tip Zorunluluk Açıklama
locale string Hayır iyzico istek sonucunda dönen metinlerin dilini ayarlamak için kullanılır. Varsayılan değeri tr’dir.
conversationId String Hayır İstek esnasında gönderip, sonuçta alabileceğiniz bir değer, request/response eşleşmesi yapmak için kullanılabilir.
callbackUrl String Evet Ödeme sonucunun başarılı veya hatalı olduğunu üye işyerine bildirmek üzere alınan URL adresi.
pricingPlanReferenceCode String Evet Aboneliğin başlatılacağı plana ait referans kodu.
subscriptionInitialStatus String Hayır ACTIVE veya PENDING değeri alır. Eğer gönderilmez ise abonelik aktif olarak başlar.
name String Evet Üye işyeri tarafındaki alıcıya ait ad.
surname String Evet Üye işyeri tarafındaki alıcıya ait soyad.
identityNumber String Evet Üye işyeri tarafındaki alıcıya ait kimlik (TCKN) numarası.
email String Evet Üye işyeri tarafındaki alıcıya ait e-posta bilgisi. E-posta adresi alıcıya ait geçerli ve erişilebilir bir adres olmalıdır.
gsmNumber String Hayır Üye işyeri tarafındaki alıcıya ait GSM numarası.
contactName(BillingAddress) String Evet Üye işyeri tarafındaki fatura adresi, ad, soyad bilgisi.
city(BillingAddress) String Evet Üye işyeri tarafındaki fatura adresi şehir bilgisi.
country(BillingAddress) String Evet Üye işyeri tarafındaki fatura adresi ülke bilgisi.
address(BillingAddress) String Evet Üye işyeri tarafındaki fatura adresi.
zipCode(BillingAddress) String Hayır Üye işyeri tarafındaki fatura adresi posta kodu.
contactName(ShippingAddress) String Evet Üye işyeri tarafındaki teslimat adresi ad soyad bilgisi. Sepetteki ürünlerden en az 1 tanesi fiziksel ürün (itemType=PHYSICAL) ise zorunludur.
city(ShippingAddress) String Evet Üye işyeri tarafındaki teslimat adresi şehir bilgisi. Sepetteki ürünlerden en az 1 tanesi fiziksel ürün (itemType=PHYSICAL) ise zorunludur.
country(ShippingAddress) String Evet Üye işyeri tarafındaki teslimat adresi ülke bilgisi. Sepetteki ürünlerden en az 1 tanesi fiziksel ürün (itemType=PHYSICAL) ise zorunludur.
address(ShippingAddress) String Evet Üye işyeri tarafındaki teslimat adresi. Sepetteki ürünlerden en az 1 tanesi fiziksel ürün (itemType=PHYSICAL) ise zorunludur.
zipCode(ShippingAddress) String Hayır Üye işyeri tarafındaki teslimat adresi posta kodu.

    Servisten dönen parametreler şu şekildedir:

Parametre ismi Tip Açıklama
status String Yapılan isteğin sonucunu bildirir. İşlem başarılı ise success, hatalı ise failure döner.
systemTime Integer Dönen sonucun o anki unix timestamp değeridir.
locale String İstekte belirtilen locale değeri geri dönülür, varsayılan değeridir.
conversationId String İstek esnasında gönderilmişse, sonuçta aynen geri iletilir.
checkoutFormContent String Checkout formun açılması için gereken HTML kod.
token String Checkout form için oluşturulan tekil değer. Her istek için özel üretilir ve işyerine dönülür. Ödemenin sonucunu öğrenmek için kullanılır
tokenExpireTime Integer Checkout form için üretilmiş olan token değerinin geçerlilik süresi.

Dönen cevap içerisindeki checkoutFormContent parametresi iyzico ödeme formunu oluşturmak için gerekli HTML kodunu içermektedir. chekoutFormContent parametresini bastırdığınız sayfada aşağıdaki "div" satırını eklediğiniz alanda ödeme formu oluşacaktır.

Responsive kullanım <div id="iyzipay-checkout-form" class="responsive"></div>

Pop-up kullanım <div id="iyzipay-checkout-form" class="popup"></div>

CHECKOUT FORM SONUCU KONTROLÜ

Abonelik için oluşturulan ödeme formuna kart bilgileri girilip "X TL Öde" butonuna basıldığında; karttan 1 TL çekilerek kartın geçerliliği kontrol edilir. Bu tutar hemen iade edilir ve kullanıcı ödeme formunu oluştururken belirlenen callbackUrl adresine yönlenir. Bu adrese bir token değeri post edilir. Üye iş yeri bu token değeri ile ikinci bir sorgu yapıp abonelik sonucunu öğrenmelidir. Bu sorguda kullanacağınız token değerini ödeme formunu oluşturduğunuz anda ya da callbackUrl adresinize iyzico tarafından post edildiğinde alabilirsiniz.

Cevapta dönecek status success ve subscriptionStatus ACTIVE veya PENDING ise abonelik başarıyla oluşturulmuş demektir.

Servise gönderilmesi gereken parametreler şu şekildedir:

Parametre ismi Tip Zorunluluk Açıklama
locale String Hayır iyzico istek sonucunda dönen metinlerin dilini ayarlamak için kullanılır. Varsayılan değeri tr’dir.
conversationId String Hayır İstek esnasında gönderip, sonuçta alabileceğiniz bir değer, request/response eşleşmesi yapmak için kullanılabilir.
token String Evet Checkout form için oluşturulan tekil değer. Her istek için özel üretilir ve işyerine dönülür. Abonelik sonucunu öğrenmek için zorunlu bir alandır.

    Servisten dönen parametreler şu şekildedir:

Parametre ismi Tip Açıklama
status String Yapılan isteğin sonucunu bildirir. İşlem başarılı ise success, hatalı ise failure döner.
systemTime Integer Dönen sonucun o anki unix timestamp değeridir.
referenceCode String Abonelik için üretilen eşsiz referans kodu
parentReferenceCode String Abonelik güncellemelerinde üye işeyerinin eşleştirme yapılabileceği eşsiz referans kodu.
pricingPlanReferenceCode Integer Aboneliğe ait plan referans kodu
customerReferenceCode String Müşteri bilgilerine istinaden oluşturulmuş eşsiz müşteri kodu. Bu kod email adresi baz alınarak oluşturulur ve müşteri işlemleri bu kod ile de yapılabilir.
subscriptionStatus String Abonelik durumunu gösterir. İstek esnasında gönderilmişse, sonuçta aynen geri iletilir. Gönderilmemişse ACTIVE değeri döner
trialDays Integer Ödeme planında belirlenen deneme süresidir. Bu süreç boyunca karttan ödeme alınmaz.
trialStartDate Integer Deneme süresinin başlangıç tarihini gösteren unix timestamp değeridir.
trialEndDate Long Deneme süresinin bitiş tarihini gösteren unix timestamp değeridir.
createdDate Long Abonelik oluşturulma tarihinin unix timestamp değeridir.
startDate Long Abonelik başlangıç tarihinin unix timestamp değeridir.