Abonelik İşlemleri

Abonelik işlemleri içerisinde yer alan servisler aşağıda listelenmiştir.

Abonelik işlemlerinde ilk işlem dahil, tüm işlemler NON3D olarak gerçekleştirilmektedir.

Abonelik Başlatma

Tüm aşamaları tamamlandıysanız artık abonelik başlatabilirsiniz.

Abonelik 2 farklı şekilde başlatılabilir.

Yukarıdaki her iki metod aynı sonucu verir ancak kullanım şeklinde farklılık vardır.

Abonelik süreci her zaman için ACTIVE veya PENDING durumu ile başlar. Eğer durum PENDING ise veya durum ACTIVE ancak ödeme planında bir deneme süresi belirtilmişse, iyzico abonelik isteğinde sadece kartın validasyonunu gerçekleştirir. Kart validasyonu 1 TL’lik bir çekim ve akabinde iade ile gerçekleşir. Bunun dışında herhangi bir işlem veya ödeme gerçekleşmez.

Eğer abonelik durumu ACTIVE ise ve planlamada herhangi bir deneme süresi belirtilmemişse karttan planda belirtilen ödeme alınır ve aboneliği başlatılmış olur.

Her abonelik bir kart bilgisi gerektirir. Müşterileriniz iyzico ortamında sakladıkları kartlar ile veya yeni bir kart ile abonelik başlatabilir. Kart güncellemesi isteğinde ilgili aboneliğe ait subscriptionReferenceCode gönderilmelidir. Bu durumda sadece ilgili aboneliğin kart bilgisi güncellenecektir.

Abonelik Durumlarının Tablosu

DURUMU

AÇIKLAMA

ACTIVE

Bir abonelik aktif ise ve ödemeler düzenli olarak alınıyorsa status active olur.

PENDING

Bir abonelik durdurulmuşsa status pending olur.

UNPAID

Abonelik sırasında ödeme alınamamış ise status unpaid olur.

UPGRADED

Abonelik başka bir plan ile güncellenmişse status upgraded olur.

CANCELED

Abonelik iptal edilmişse status cancelled olur.

EXPIRED

Abonelik periyodu bitmişse status expired olur. Karttan başka bir ödeme alınmaz.

Ödeme Formu ile Abonelik Başlatma

Bir checkout form oluşturmak için üye işyerleri aşağıdaki bilgileri göndermelidir.

Ödeme Planı Referans Kodu
Müşteri Bilgisi
Abonelik Durumu
CallBackURL (Checkout Form sonucunun post edileceği adres)

CallBackUrl üye işyerleri tarafından istek sırasında verilir ve ödeme yapıldıktan sonra son kullanıcının yönlendirileceği sayfayı belirler. Müşteri ödemeyi yaptığı anda yönlendirme gerçekleşir. Bu noktada ödeme isteği bankaya gönderilmiş ve sonuç iyzico tarafında işlenmiştir. Üye işyeri ayrı bir istekle ödemenin alınıp alınmadığını kontrol etmelidir. Eğer kart validasyonu veya ilk ödeme başarılıysa diğer tüm süreç iyzico tarafında ilerletilir.

NOT : Müşterinizin iyzico ortamında sakladığı bir kart varsa checkout formunda saklı kartla ödeme seçeneği görünecektir. Bu durumda üye iş yerlerimizin ek bir istek göndermesi gerekmez.

iyzico Checkout Form oluşturma isteği sonucunda bir htmlContent parametresi döner. Bu javascript kod parçacığı sayfaya yazdırıldığında, iyzico kütüphanesi aşağıda belirtilen “div” lerin herhangi birine yüklenmeye hazırdır. Sayfa tamamen yüklendiğinde checkout form görünecektir.

Checkout formun yükleneceği div'ler responsive veya popup şeklinde olabilir. Aşağıda örnekleri iletilmiştir.

<div id="iyzipay-checkout-form" class="responsive"></div>

<div id="iyzipay-checkout-form" class="popup"></div>

Abonelik Başlatma (iyzico Ödeme Formu)

post

iyzico Ödeme formu (Checkout Form) ile abonelik başlatmak için kullanılır. Ödeme formuna ait content ve token değeri döner.

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Content-TypestringRequired

İstek içeriğinin formatı.

Example: application/json

Body

localestring · enumOptional

Dil kodu. Varsayılan; tr. Ödeme formunun İngilizce oluşturulması için "en" gönderilmelidir.

Example: trPossible values:

callbackUrlstringRequired

Ödeme sonucunun gönderileceği callback adresi.

Example: https://callbackUrl.com

pricingPlanReferenceCodestringRequired

Aboneliğin başlatılacağı planın referans kodu.

Example: 7515f763-5da3-4a35-8f7f-d425ae44ac04

subscriptionInitialStatusstring · enumRequired

Abonelik başlangıç durumu. PENDING gönderilirse abonelik başlamaz ve tekrar aktif edilmesi gerekir.

Example: ACTIVEPossible values:

conversationIdstringOptional

İstek esnasında gönderip, sonuçta alabileceğiniz bir değer, request/response eşleşmesi yapmak için kullanılabilir.

Example: 123456789

Responses

200

Başarılı yanıt

application/json

400

Başarısız yanıt

application/json

post

POST https://api.iyzipay.com/v2/subscription/checkoutform/initialize
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "callbackUrl": "https://callbackUrl.com",
  "pricingPlanReferenceCode": "7515f763-5da3-4a35-8f7f-d425ae44ac04",
  "subscriptionInitialStatus": "ACTIVE",
  "conversationId": "conversationId",
  "customer": {
    "name": "John",
    "surname": "Stone",
    "email": "[email protected]",
    "gsmNumber": "+905545545512",
    "identityNumber": "1234567890",
    "billingAddress": {
      "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
      "zipCode": "34345",
      "contactName": "contactName",
      "city": "Istanbul",
      "country": "Türkiye"
    },
    "shippingAddress": {
      "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
      "zipCode": "34345",
      "contactName": "contactName",
      "city": "Istanbul",
      "country": "Türkiye"
    }
  }
}

{
  "status": "success",
  "locale": "tr",
  "systemTime": 1755596201712,
  "conversationId": "conversationId",
  "token": "a9f91f36-2110-4c55-848e-bdd2c7016171",
  "checkoutFormContent": "<script type=\"text/javascript\">if (typeof iyziInit == 'undefined') {var iyziInit = {currency:\"TRY\",token:\"a9f91f36-2110-4c55-848e-bdd2c7016171\",price:1.00,...}};</script>",
  "tokenExpireTime": 1800
}

Son kullanıcı kredi kartı bilgilerini girip veya saklı kartı ile ödemeyi tamamladığında, işlem başarılı ise, sayfa init isteğinde belirtilen callBackUrl adresine yönlendirilir. Bu adrese aynı zamanda post metodu ile token bilgisi gönderilir. Bu sorguda kullanacağınız token değerini ödeme formunu oluşturduğunuz anda(init) ya da callbackUrl adresinize gönderilen post datasından alabilirsiniz.

Örnek Kodlar

Ödeme Formu Sonucunu Alma

get

Checkout form akışı tamamlandıktan sonra ödeme formuna token ile abonelik başlatma sonucunu sorgulanır.

Path parameters

tokenstringRequired

Checkout form initialize ile dönen, ilgili işleme ait token.

Query parameters

conversationIdstringOptional

İstek esnasında gönderip, sonuçta alabileceğiniz bir değer, request/response eşleşmesi yapmak için kullanılabilir.

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Content-TypestringRequired

İstek içeriğinin formatı.

Example: application/json

Responses

200

Başarılı yanıt

application/json

400

Başarısız yanıt

application/json

get

GET https://api.iyzipay.com/v2/subscription/checkoutform/1590292b-bed2-4909-8833-6c6f85d7ec17
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "status": "success",
  "systemTime": 1755597000000,
  "token": "a9f91f36-2110-4c55-848e-bdd2c7016171",
  "data": {
    "referenceCode": "8d06cc19-98fb-47a6-ae1f-47f20c4797b4",
    "parentReferenceCode": "535094d2-9257-401b-8e38-f08308e37098",
    "pricingPlanReferenceCode": "515f763-5da3-4a35-8f7f-d425ae44ac04",
    "customerReferenceCode": "775ba402-41f0-4674-968b-43cc787d9366",
    "subscriptionStatus": "ACTIVE",
    "trialDays": 5,
    "trialStartDate": 1755599766595,
    "trialEndDate": 1756031766595,
    "createdDate": 1755599766595,
    "startDate": 1755599766595,
    "endDate": 1787567766595
  }
}

Örnek Kodlar

PHP

Java

Node.Js

Abonelik Başlatma (NON3D)

post

Hazır ödeme formu olmadan, Tarafınıza ait ödeme formu ile NON3D servisi üzerinden abonelik başlatabilirsiniz.

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Content-TypestringRequired

İstek içeriğinin formatı.

Example: application/json

Body

pricingPlanReferenceCodestringRequired

Aboneliğin başlatılacağı planın referans kodu.

Example: 7515f763-5da3-4a35-8f7f-d425ae44ac04

conversationIdstringOptional

İstek esnasında gönderip, sonuçta alabileceğiniz bir değer, request/response eşleşmesi yapmak için kullanılabilir.

Example: 123456789

subscriptionInitialStatusstring · enumRequired

Abonelik başlangıç durumu. PENDING gönderilirse abonelik başlamaz ve tekrar aktif edilmesi gerekir.

Example: ACTIVEPossible values:

Responses

200

Başarılı yanıt

application/json

400

Başarısız yanıt

application/json

post

POST https://api.iyzipay.com/v2/subscription/initialize
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "tr",
  "pricingPlanReferenceCode": "7515f763-5da3-4a35-8f7f-d425ae44ac04",
  "conversationId": "conv-1001",
  "subscriptionInitialStatus": "ACTIVE",
  "customer": {
    "name": "John",
    "surname": "Stone",
    "email": "[email protected]",
    "gsmNumber": "+905545545512",
    "identityNumber": "1234567890",
    "billingAddress": {
      "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
      "contactName": "contactName",
      "city": "Istanbul",
      "country": "Türkiye"
    },
    "shippingAddress": {
      "address": "address",
      "zipCode": "zipCode",
      "contactName": "contactName",
      "city": "city",
      "country": "country"
    }
  },
  "paymentCard": {
    "cardHolderName": "John Doe",
    "cardNumber": "5528790000000008",
    "expireMonth": "12",
    "expireYear": "2030",
    "cvc": "123"
  }
}

{
  "status": "success",
  "systemTime": 1755598000000,
  "data": {
    "referenceCode": "8d06cc19-98fb-47a6-ae1f-47f20c4797b4",
    "parentReferenceCode": "535094d2-9257-401b-8e38-f08308e37098",
    "pricingPlanReferenceCode": "515f763-5da3-4a35-8f7f-d425ae44ac04",
    "customerReferenceCode": "775ba402-41f0-4674-968b-43cc787d9366",
    "subscriptionStatus": "ACTIVE",
    "trialDays": 5,
    "trialStartDate": 1755599766595,
    "trialEndDate": 1756031766595,
    "createdDate": 1755599766595,
    "startDate": 1755599766595,
    "endDate": 1787567766595
  }
}

Örnek Kodlar

Abonelik Başlatma (Existing Customer)

post

Abonelik başlatılmak istenen kullanıcının hali hazırda aktif bir aboneliği bulunuyorsa, customerReferenceCode ile yeni bir abonelik başlatılabilir. Eğer kullanıcının aktif bir aboneliği bulunmuyorsa custormerReferenceCode ile yeni bir abonelik başlatılmamaktadır.

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Content-TypestringRequired

İstek içeriğinin formatı.

Example: application/json

Body

subscriptionInitialStatusstring · enumRequired

Abonelik başlangıç durumu. PENDING gönderilirse abonelik başlamaz ve tekrar aktif edilmesi gerekir.

Example: ACTIVEPossible values:

pricingPlanReferenceCodestringRequired

Aboneliğin başlatılacağı planın referans kodu.

Example: 7515f763-5da3-4a35-8f7f-d425ae44ac04

customerReferenceCodestringRequired

Mevcut müşterinin referans kodu. Aktif bir aboneliği olmalıdır.

Example: 279bb493-6fda-45e9-9368-2373ea43ff8d

Responses

200

Başarılı yanıt

application/json

400

Başarısız yanıt

application/json

post

POST https://api.iyzipay.com/v2/subscription/initialize/with-customer
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "subscriptionInitialStatus": "ACTIVE",
  "pricingPlanReferenceCode": "7515f763-5da3-4a35-8f7f-d425ae44ac04",
  "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d"
}

{
  "status": "success",
  "systemTime": 1755606762264,
  "data": {
    "referenceCode": "009dac1a-00dc-41e8-a92f-2c24b18e27b9",
    "parentReferenceCode": "f4bb665b-a48a-4100-917f-d7a46b16e586",
    "pricingPlanReferenceCode": "7515f763-5da3-4a35-8f7f-d425ae44ac04",
    "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
    "subscriptionStatus": "ACTIVE",
    "trialDays": 5,
    "trialStartDate": 1755606762238,
    "trialEndDate": 1756038762238,
    "createdDate": 1755606762238,
    "startDate": 1755606762238,
    "endDate": 1787574762238
  }
}

Örnek Kodlar

PHP

Java

Node.Js

Abonelik Aktifleştirme

post

Pending durumunda başlatılan bir abonelik, bu servis üzerinden aktif hale getirilir.

Path parameters

subscriptionReferenceCodestringRequired

Pending olarak başlatılan aboneliğe ait referans kodu.

Example: a2077643-bab7-4b73-85a5-7676c78d7c66

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Content-TypestringRequired

İstek içeriğinin formatı.

Example: application/json

Body

subscriptionReferenceCodestringOptional

Pending oalrak başlatılan aboneliğe ait referans kodu.

Example: a2077643-bab7-4b73-85a5-7676c78d7c66

Responses

200

Başarılı yanıt

application/json

400

Başarısız yanıt

application/json

post

POST https://api.iyzipay.com/v2/subscription/subscriptions/009dac1a-00dc-41e8-a92f-2c24b18e27b9/activate
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "referenceCode": "a2077643-bab7-4b73-85a5-7676c78d7c66"
}

{
  "status": "success",
  "systemTime": 1687096973255
}

Örnek Kodlar

Abonelik Ödeme Tekrarlama

post

Eğer bir abonelikte, tekrarlayan ödemeler sırasında bir ödeme başarısız olduysa, işlemi tekrar denemek ve ödemeyi almak için retry servisi kullanılır.

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Content-TypestringRequired

İstek içeriğinin formatı.

Example: application/json

Body

referenceCodestringRequired

Başarısız ödemenin referans kodu. Başarısız abonelik ödemesi için gönderilen webhook bildiriminde yer alan orderReferenceCode değeridir.

Example: 009dac1a-00dc-41e8-a92f-2c24b18e27b9

Responses

200

Başarılı yanıt

application/json

400

Başarısız yanıt

application/json

post

POST https://api.iyzipay.com/v2/subscription/operation/retry
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "referenceCode": "a2077643-bab7-4b73-85a5-7676c78d7c66"
}

{
  "status": "success",
  "systemTime": 1687096973255
}

Örnek Kodlar

Abonelik Yükseltme

post

Abonelik süresince plan değiştirmek veya yükseltmek mümkündür. Bunun için yeni planın aynı ürüne ait olması ve ödeme aralığının (paymentInterval ve paymentIntervalCount) aynı olması gerekir. Fiyat güncellemeleri için abonelik yükseltme servisi kullanılır.

Path parameters

subscriptionReferenceCodestringRequired

Yükseltilmek istenen aboneliğe ait referans kodu.

Example: 97fb885d-69e3-49ac-8590-9d05c9c6016e

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Content-TypestringRequired

İstek içeriğinin formatı.

Example: application/json

Body

upgradePeriodstring · enumRequired

Aboneliğin upgrade edileceği tarih. Değerler:

NOW: Değişiklik/işlem hemen uygulanır.
NEXT_PERIOD: Değişiklik bir sonraki faturalama döneminde uygulanır.

Example: NOWPossible values:

newPricingPlanReferenceCodestringRequired

Yükseltilmek istenen ödeme planına ait referans kodu.

Example: dbffa857-40f5-48d1-9179-e9326ffb942d

useTrialbooleanOptional

Eğer true gönderilirse upgrade edilen ödeme planının deneme süreci dahil edilir.

Example: false

resetRecurrenceCountbooleanOptional

true: Yeni planın tekrar sayısına (recurrenceCount) göre abonelik bitiş tarihi yeniden hesaplanır.
false: Mevcut planın bitiş tarihi korunur ve yeni plana aktarılır.

Example: true

Responses

200

Başarılı yanıt

application/json

400

Başarısız yanıt

application/json

post

POST https://api.iyzipay.com/v2/subscription/subscriptions/97fb885d-69e3-49ac-8590-9d05c9c6016e/upgrade
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "newPricingPlanReferenceCode": "dbffa857-40f5-48d1-9179-e9326ffb942d",
  "upgradePeriod": "NEXT_PERIOD",
  "useTrial": false,
  "resetRecurrenceCount": true
}

{
  "status": "success",
  "systemTime": 1755613834401,
  "data": {
    "referenceCode": "74726a5a-cc3d-4de8-b08c-3e373ea26842",
    "parentReferenceCode": "85626e75-5043-4343-89bd-3cbbf33d15ad",
    "pricingPlanReferenceCode": "dbffa857-40f5-48d1-9179-e9326ffb942d",
    "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
    "subscriptionStatus": "ACTIVE",
    "trialDays": 0,
    "createdDate": 1755613834375,
    "startDate": 1756045826566,
    "endDate": 1787581826566
  }
}

Örnek Kodlar

Abonelik İptali

post

Aktif bir aboneliği iptal etmek için kullanılır.

Path parameters

subscriptionReferenceCodestringRequired

İptal edilmek istenen aboneliğe ait referans kodu.

Example: 009dac1a-00dc-41e8-a92f-2c24b18e27b9

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Content-TypestringRequired

İstek içeriğinin formatı.

Example: application/json

Body

subscriptionReferenceCodestringOptional

Abonelik referans kodu. Opsiyonel olarak body de gönderilebilir.

Example: a2077643-bab7-4b73-85a5-7676c78d7c66

Responses

200

Başarılı yanıt

application/json

400

Başarısız yanıt

application/json

post

POST https://api.iyzipay.com/v2/subscription/subscriptions/009dac1a-00dc-41e8-a92f-2c24b18e27b9/cancel
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "subscriptionReferenceCode": "a2077643-bab7-4b73-85a5-7676c78d7c66"
}

{
  "status": "success",
  "systemTime": 1687096973255
}

Örnek Kodlar

Abonelik Detayı

get

Aboneliğe ait referans kod ile sorgulama yapılarak bir aboneliğin tüm detayları bu istek ile görülebilir.

Path parameters

subscriptionReferenceCodestringRequired

İlgili aboneliğe ait referans kodu.

Example: 732a16cc-2ec4-4399-9aab-656cb6f5249e

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Content-TypestringRequired

İstek içeriğinin formatı.

Example: application/json

Body

subscriptionReferenceCodestringOptional

Abonelik referans kodu. Opsiyonel olarak body de gönderilebilir.

Example: 732a16cc-2ec4-4399-9aab-656cb6f5249e

Responses

200

Başarılı yanıt

application/json

get

GET https://api.iyzipay.com/v2/subscription/subscriptions/732a16cc-2ec4-4399-9aab-656cb6f5249e
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

200

Başarılı yanıt

{
  "status": "success",
  "systemTime": 1755617091761,
  "data": {
    "totalCount": 1,
    "currentPage": 1,
    "pageCount": 1,
    "items": [
      {
        "referenceCode": "732a16cc-2ec4-4399-9aab-656cb6f5249e",
        "parentReferenceCode": "aa86bbf7-176f-432e-8523-7c24cc250af4",
        "pricingPlanName": "Ödeme Planı V2 TEST",
        "pricingPlanReferenceCode": "deadd767-7d0a-4ddb-96f2-565ad245773d",
        "productName": "test",
        "productReferenceCode": "40070483-1a6e-4641-99c0-be513edcf9f2",
        "customerEmail": "[email protected]",
        "customerGsmNumber": "+905554445555",
        "customerReferenceCode": "ce88a44d-a4f5-4de9-8bbb-1f170a9be219",
        "subscriptionStatus": "UNPAID",
        "trialDays": 0,
        "createdDate": 1753186413089,
        "startDate": 1753186413089,
        "endDate": 1753229613089,
        "orders": [
          {
            "referenceCode": "684279ad-5caa-40a0-ae9a-95ec097d696d",
            "price": 1.4,
            "currencyCode": "TRY",
            "startPeriod": 1753190013089,
            "endPeriod": 1753193613089,
            "orderStatus": "WAITING",
            "paymentAttempts": [
              {
                "conversationId": "90cf2fdc-bb9a-4931-be32-f65312eb379d",
                "createdDate": 1753190040185,
                "paymentStatus": "FAILED",
                "errorCode": "5034",
                "errorMessage": "buyerSurname gönderilmesi zorunludur"
              }
            ]
          },
          {
            "referenceCode": "0759e5ce-1668-40cb-9570-d0b6eda8d988",
            "price": 1.4,
            "currencyCode": "TRY",
            "startPeriod": 1753186413089,
            "endPeriod": 1753190013089,
            "orderStatus": "SUCCESS",
            "paymentAttempts": [
              {
                "conversationId": "123456789",
                "createdDate": 1753186413090,
                "paymentId": 24578296,
                "paymentStatus": "SUCCESS"
              }
            ]
          }
        ]
      }
    ]
  }
}

Örnek Kodlar

Abonelik Arama

get

Farklı parametrelerle filtreleme yaparak veya herhangi bir parametre kullanmadan sorgulama yaparak abonelik ve ödeme bilgilerinin detaylarına ulaşmayı sağlar. Örneğin sadece subscriptionStatus göndererek, belirtilen statüdeki abonelikleri listeleyebilirsiniz.

Path parameters

subscriptionReferenceCodestringOptional

Sorgulanacak aboneliğe ait referans kodu.

Example: 97fb885d-69e3-49ac-8590-9d05c9c6016e

customerReferenceCodestringOptional

Müşteri referans kodu.

Example: 279bb493-6fda-45e9-9368-2373ea43ff8d

pricingPlanReferenceCodestringOptional

Abonelikte kullanılan ödeme planına ait referans kodu.

Example: dbffa857-40f5-48d1-9179-e9326ffb942d

parentstringOptional

Abonelik güncellemelerinde eşleştirme için kullanılan üst (parent) referans kodu.

Example: 670489f2-9224-4a71-af6c-7044d22f5d73

subscriptionStatusstring · enumOptional

Abonelik durumu filtresi.

Example: ACTIVEPossible values:

startDateintegerOptional

Abonelik başlangıç tarihi.

Example: 2025-08-24 14:30:26

endDateintegerOptional

Abonelik bitiş tarihi (epoch ms).

Example: 2025-08-24 14:30:26

pageintegerOptional

Sayfa numarası.

Example: 1

countintegerOptional

Sayfa başına kayıt adedi.

Example: 20

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Content-TypestringRequired

İstek içeriğinin formatı.

Example: application/json

Responses

200

Başarılı yanıt

application/json

404

Yanlış endpoint (ör. yazım hatası) durumda dönebilecek örnek.

application/json

get

GET https://api.iyzipay.com/v2/subscription/subscriptions?startDate=2025-08-24 14:30:26&endDate=2026-08-24 14:30:26&subscriptionStatus=ACTIVE 
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "status": "success",
  "systemTime": 1755683471024,
  "data": {
    "totalCount": 4,
    "currentPage": 1,
    "pageCount": 1,
    "items": [
      {
        "referenceCode": "74726a5a-cc3d-4de8-b08c-3e373ea26842",
        "parentReferenceCode": "85626e75-5043-4343-89bd-3cbbf33d15ad",
        "pricingPlanName": "Ödeme Planı Adı",
        "pricingPlanReferenceCode": "dbffa857-40f5-48d1-9179-e9326ffb942d",
        "productName": "Çay",
        "productReferenceCode": "8d562f84-f8d5-441a-b086-9483fc5133a0",
        "customerEmail": "[email protected]",
        "customerGsmNumber": "+905554443322",
        "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
        "subscriptionStatus": "ACTIVE",
        "trialDays": 0,
        "createdDate": 1755613834375,
        "startDate": 1756045826566,
        "endDate": 1787581826566,
        "orders": [
          {
            "referenceCode": "0ad2563a-f5b7-4a6c-b6ec-9dc7548493ec",
            "price": 10,
            "currencyCode": "TRY",
            "startPeriod": 1756045826566,
            "endPeriod": 1758724226566,
            "orderStatus": "WAITING",
            "paymentAttempts": []
          }
        ]
      },
      {
        "referenceCode": "52c732ba-b449-460b-b553-ab21f9074300",
        "parentReferenceCode": "670489f2-9224-4a71-af6c-7044d22f5d73",
        "pricingPlanName": "Ödeme Planı Adı",
        "pricingPlanReferenceCode": "dbffa857-40f5-48d1-9179-e9326ffb942d",
        "productName": "Çay",
        "productReferenceCode": "8d562f84-f8d5-441a-b086-9483fc5133a0",
        "customerEmail": "[email protected]",
        "customerGsmNumber": "+905554443322",
        "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
        "subscriptionStatus": "ACTIVE",
        "trialDays": 0,
        "createdDate": 1755613786569,
        "startDate": 1756045757180,
        "endDate": 1787581757180,
        "orders": [
          {
            "referenceCode": "9723fa25-0968-4677-bd9a-559389252b58",
            "price": 10,
            "currencyCode": "TRY",
            "startPeriod": 1756045757180,
            "endPeriod": 1758724157180,
            "orderStatus": "WAITING",
            "paymentAttempts": []
          }
        ]
      },
      {
        "referenceCode": "d5044ccc-f346-4a8c-81e7-272516a330a9",
        "parentReferenceCode": "6f0d463e-9a32-47ea-9a17-53d283f7f6ba",
        "pricingPlanName": "Ödeme Planı Adı",
        "pricingPlanReferenceCode": "dbffa857-40f5-48d1-9179-e9326ffb942d",
        "productName": "Çay",
        "productReferenceCode": "8d562f84-f8d5-441a-b086-9483fc5133a0",
        "customerEmail": "[email protected]",
        "customerGsmNumber": "+905554443322",
        "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
        "subscriptionStatus": "ACTIVE",
        "trialDays": 0,
        "createdDate": 1755613607741,
        "startDate": 1756045126208,
        "endDate": 1787581126208,
        "orders": [
          {
            "referenceCode": "e8c6d7f2-556d-4976-a44f-82e7f5b533c0",
            "price": 10,
            "currencyCode": "TRY",
            "startPeriod": 1756045126208,
            "endPeriod": 1758723526208,
            "orderStatus": "WAITING",
            "paymentAttempts": []
          }
        ]
      },
      {
        "referenceCode": "5e4b1ec2-b0c0-47bf-b1bf-8656355cb82d",
        "parentReferenceCode": "7a67a645-3d81-4207-bab4-76beade2f6be",
        "pricingPlanName": "Güncel Plan",
        "pricingPlanReferenceCode": "7515f763-5da3-4a35-8f7f-d425ae44ac04",
        "productName": "Çay",
        "productReferenceCode": "8d562f84-f8d5-441a-b086-9483fc5133a0",
        "customerEmail": "[email protected]",
        "customerGsmNumber": "+905554443322",
        "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
        "subscriptionStatus": "ACTIVE",
        "trialDays": 5,
        "trialStartDate": 1755609729652,
        "trialEndDate": 1756041729652,
        "createdDate": 1755609702703,
        "startDate": 1755609729652,
        "orders": [
          {
            "referenceCode": "664a7e09-8ca2-45d8-9996-b340a94d90cb",
            "price": 99.99,
            "currencyCode": "TRY",
            "startPeriod": 1756041729652,
            "endPeriod": 1758720129652,
            "orderStatus": "WAITING",
            "paymentAttempts": []
          }
        ]
      }
    ]
  }
}

Örnek Kodlar

Abonelik Kart Güncelleme (Checkout Form)

post

Bu istek ile bir abonelikte kullanılan kredi kartı güncellenebilir. Ödeme hatası, kart son kullanma tarihinin geçmesi gibi durumlarda üye iş yerleri kart bilgisini kolayca güncelleyebilir. Güncelleme işlemi yalnızca iyzico ödeme formu üzerinden gerçekleştirilir. Güncellenen kredi kartının validasyonu için 1 TL’lik ödeme alınır ve hemen iadesi gerçekleşir.

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Content-TypestringRequired

İstek içeriğinin formatı.

Example: application/json

Body

callbackUrlstringRequired

Güncelleme sonucunun gönderileceği callback adresi.

Example: https://www.merchant.com/callback

customerReferenceCodestringRequired

Kartı güncellenecek müşteriye ait referans kodu.

Example: 279bb493-6fda-45e9-9368-2373ea43ff8d

subscriptionReferenceCodestringOptional

Bir abonelik üzerinde güncelleme sağlanacaksa, işlem yapılacak aboneliğe ait referans kodu (opsiyonel).

Example: 52c732ba-b449-460b-b553-ab21f9074300

localestring · enumOptional

İstek sonrası dönüş yapılacak yanıt dili.

Example: trPossible values:

Responses

200

Başarılı yanıt

application/json

400

Başarısız yanıt

application/json

post

POST https://api.iyzipay.com/v2/subscription/card-update/checkoutform/initialize
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "tr",
  "callbackUrl": "https://www.merchant.com/callback",
  "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
  "subscriptionReferenceCode": "52c732ba-b449-460b-b553-ab21f9074300"
}

{
  "status": "success",
  "locale": "tr",
  "systemTime": 1755679946462,
  "conversationId": "04c6063d-eb03-4817-ba87-33b81e392ecf",
  "token": "83832cc6-89b6-4a83-ac9f-dd996a52b2cb",
  "checkoutFormContent": "<script type=\"text/javascript\">if (typeof iyziInit == 'undefined') {var iyziInit = {currency:\"TRY\",token:\"83832cc6-89b6-4a83-ac9f-dd996a52b2cb\",price:1.00,...}};</script>",
  "tokenExpireTime": 1800
}

Bu istek ile checkout form oluşturulur ve müşteri ödemeyi yaptığında belirtilen callBackUrl adresine token bilgisi post edililir. Bu durumda kart başarıyla güncellenmiş demektir.

Örnek Kodlar

NOT : Üye işyerleri tüm isteklerde locale ve conversationId parametrelerini gönderebilir ancak bu zorunlu değildir. Locale parametresi cevabın dilini belirler. Eğer “EN” olarak belirtilirse hata mesajları İngilizce alınacaktır. Conversation id ise yazılımcıların istek ve cevapları eşleştirmede kullanabilecekleri bir değerdir. Bu parametre gönderilirse cevapta aynı değer alınacaktır.

Last updated 8 days ago