Ctrlk
GitHubFeedback FormAPI Reference - Beta
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Kart Saklama

Kullanıcı ve Kart Oluşturma

post

Ödeme oluşturmadan, iyzico'da bir kullanıcı ve bu kullanıcıya bağlı bir kart kaydı oluşturabilirsiniz. Veya aynı endpoint üzerinden mevcut kullanıcıya yeni bir kart ekleyebilirsiniz. Bu noktada, istek parametreleri değişir. Her iki isteğin, request body ve json verilerine ulaşabilirsiniz;

Header parameters
AuthorizationstringRequired

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

Content-TypestringRequired

İstek gövdesinin veri formatı.

Example: application/json
Body
or
Responses
200

Başarılı yanıt

application/json

Standart yanıt alanları.

statusstring · enumOptional

Yapılan isteğin sonucunu bildirir.

Example: successPossible values:
localestringOptional

Yanıt dili (tr/en).

Example: tr
systemTimeintegerOptional

İşlem zamanı (epoch ms).

Example: 1755198001941
conversationIdstringOptional

İstek esnasında gönderilmişse, yanıtta aynen geri iletilir.

Example: conversationId
pricedecimalOptional

Sepet toplam tutarı.

Example: 1
paidPricedecimalOptional

Tahsil edilen toplam tutar.

Example: 1
installmentintegerOptional

Taksit sayısı.

Example: 1
paymentIdstringOptional

Ödeme ID’si.

Example: 25149157
fraudStatusinteger · enumOptional

Fraud filtrelerine göre ödeme durumu. Eğer ödemenin fraud risk skoru düşük ise ödemeye anında onay verilir, eğer fraud risk skoru yüksek ise ödeme işlemi reddedilir. Üye işyeri sadece 1 olan işlemlerde ürünü kargoya vermelidir, 0 olan işlemler için bilgilendirme beklemelidir.

  • 1: Onaylandı
  • 0: İncelemede
  • -1: Reddedildi
Example: 1Possible values:
merchantCommissionRatedecimalOptional

Üye işyerinin uyguladığı vade/komisyon oranı. Örneğin price=100, paidPrice=110 ise üye işyeri vade/komisyon oranı %10’dur. Bilgi amaçlıdır.

Example: 10
merchantCommissionRateAmountdecimalOptional

Üye işyerinin uyguladığı vade/komisyon tutarı. Örneğin price=100, paidPrice=110 ise üye işyeri vade/komisyon tutarı 10’dur. Bilgi amaçlıdır.

Example: 0.1
iyziCommissionRateAmountdecimalOptional

iyzico komisyon oran tutarı.

Example: 0.03839
iyziCommissionFeedecimalOptional

Ödemeye ait iyzico işlem ücreti.

Example: 0.25
cardTypestring · enumOptional

Kart tipi.

Example: CREDIT_CARDPossible values:
cardAssociationstring · enumOptional

Kart kuruluşu.

Example: MASTER_CARDPossible values:
cardFamilystring · enumOptional

Kart ailesi (yerel kartlarda döner).

Example: AxessPossible values:
binNumberstringOptional

Kartın ilk 8 hanesidir.

Example: 55260800
lastFourDigitsstringOptional

Kartın son 4 hanesi.

Example: 0006
basketIdstringOptional

Sepet ID.

Example: B67832
currencystring · enumOptionalExample: TRYPossible values:
authCodestringOptional

Ödeme Fazı.

Example: 526832
phasestringOptionalExample: AUTH
hostReferencestringOptional

Ödemeye ilişkin banka tarafından verilen hostReference değeri.

Example: mock00007iyzihostrfn
signaturestringOptional

İmza doğrulaması için kullanılabilecek signature değeri.

Example: 03d01d123540295e0658e6400f096fbd346791df3838e6644740121db937e182
externalIdstringOptional

İstekle iletilen externalId değeri.

Example: 665864cefa5eac24beba9ebb
emailstringOptional

Saklanan kart üzerindeki email (yalnızca ilk varyantta dönebilir).

Example: test@test.com
cardUserKeystringOptional

Saklanan karta ait kullanıcı anahtarı. Tekrar ödeme tahsil etmek için kullanılır.

Example: d5616aac-84a4-9008-d4a7-0bc5ebc2ce68
cardTokenstringOptional

Saklı karta ait token. Tekrar ödeme tahsil etmek için kullanılır.

Example: 8fb4b2c0-3030-4a95-5fd6-a3049ca3bbd2
cardAliasstringOptional

Karta verilen isim.

Example: card alias
cardBankCodeintegerOptional

Eğer ödeme yapılan kart yerel bir kart ise, kartın ait olduğu banka kodu.

Example: 46
cardBankNamestringOptional

Eğer ödeme yapılan kart yerel bir kart ise, kartın ait olduğu banka adı.

Example: Akbank
post/cardstorage/card
POST https://api.iyzipay.com/cardstorage/card
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "tr",
  "conversationId": "conversationId",
  "externalId": "665864cefa5eac24beba9ebb",
  "email": "test@test.com",
  "card": {
    "cardAlias": "card_alias",
    "cardNumber": "5526080000000006",
    "expireYear": "2033",
    "expireMonth": "12",
    "cardHolderName": "john doe"
  }
}

{
  "status": "success",
  "locale": "tr",
  "systemTime": 1756301363865,
  "conversationId": "conversationId",
  "externalId": "665864cefa5eac24beba9ebb",
  "email": "test@test.com",
  "cardUserKey": "d5616aac-84a4-9008-d4a7-0bc5ebc2ce68",
  "cardToken": "8fb4b2c0-3030-4a95-5fd6-a3049ca3bbd2",
  "binNumber": "55260800",
  "lastFourDigits": "0006",
  "cardType": "CREDIT_CARD",
  "cardAssociation": "MASTER_CARD",
  "cardFamily": "Axess",
  "cardAlias": "card_alias",
  "cardBankCode": 46,
  "cardBankName": "Akbank"
}

Saklı Kartları Sorgulama

post

iyzico'da bir kullanıcıya ait kartları sorgulayabilirsiniz.

Header parameters
AuthorizationstringRequired

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

Content-TypestringRequired

İstek gövdesinin veri formatı.

Example: application/json
Body

Saklı kartları sorgulama isteği.

localestringOptional

Yanıt dilini belirler. Varsayılan tr.

Example: tr
conversationIdstringOptional

İstek/yanıt eşleşmesi için gönderilen ID.

Example: 23233333
cardUserKeystringRequired

Kartların listeleneceği kullanıcı anahtarı.

Example: 6abd3f19-8305-d0c9-09e2-0300b5516a38
Responses
200

Başarılı yanıt — Kart listesi

application/json

Standart yanıt alanları.

statusstring · enumOptional

Yapılan isteğin sonucunu bildirir.

Example: successPossible values:
localestringOptional

Yanıt dili (tr/en).

Example: tr
systemTimeintegerOptional

İşlem zamanı (epoch ms).

Example: 1755198001941
conversationIdstringOptional

İstek esnasında gönderilmişse, yanıtta aynen geri iletilir.

Example: conversationId
pricedecimalOptional

Sepet toplam tutarı.

Example: 1
paidPricedecimalOptional

Tahsil edilen toplam tutar.

Example: 1
installmentintegerOptional

Taksit sayısı.

Example: 1
paymentIdstringOptional

Ödeme ID’si.

Example: 25149157
fraudStatusinteger · enumOptional

Fraud filtrelerine göre ödeme durumu. Eğer ödemenin fraud risk skoru düşük ise ödemeye anında onay verilir, eğer fraud risk skoru yüksek ise ödeme işlemi reddedilir. Üye işyeri sadece 1 olan işlemlerde ürünü kargoya vermelidir, 0 olan işlemler için bilgilendirme beklemelidir.

  • 1: Onaylandı
  • 0: İncelemede
  • -1: Reddedildi
Example: 1Possible values:
merchantCommissionRatedecimalOptional

Üye işyerinin uyguladığı vade/komisyon oranı. Örneğin price=100, paidPrice=110 ise üye işyeri vade/komisyon oranı %10’dur. Bilgi amaçlıdır.

Example: 10
merchantCommissionRateAmountdecimalOptional

Üye işyerinin uyguladığı vade/komisyon tutarı. Örneğin price=100, paidPrice=110 ise üye işyeri vade/komisyon tutarı 10’dur. Bilgi amaçlıdır.

Example: 0.1
iyziCommissionRateAmountdecimalOptional

iyzico komisyon oran tutarı.

Example: 0.03839
iyziCommissionFeedecimalOptional

Ödemeye ait iyzico işlem ücreti.

Example: 0.25
cardTypestring · enumOptional

Kart tipi.

Example: CREDIT_CARDPossible values:
cardAssociationstring · enumOptional

Kart kuruluşu.

Example: MASTER_CARDPossible values:
cardFamilystring · enumOptional

Kart ailesi.

Example: AxessPossible values:
binNumberstringOptional

BIN (ilk 8 hane).

Example: 552608
lastFourDigitsstringOptional

Kartın son 4 hanesi.

Example: 0006
basketIdstringOptional

Sepet ID.

Example: B67832
currencystring · enumOptionalExample: TRYPossible values:
authCodestringOptional

Ödeme Fazı.

Example: 526832
phasestringOptionalExample: AUTH
hostReferencestringOptional

Ödemeye ilişkin banka tarafından verilen hostReference değeri.

Example: mock00007iyzihostrfn
signaturestringOptional

İmza doğrulaması için kullanılabilecek signature değeri.

Example: 03d01d123540295e0658e6400f096fbd346791df3838e6644740121db937e182
cardUserKeystringOptional

Listelemesi yapılan kullanıcı anahtarı.

Example: 7f4be1bd-1f46-3425-f2ea-3a9ecd70f182
post/cardstorage/cards
POST /cardstorage/cards HTTP/1.1
Host: api.iyzipay.com
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 96

{
  "locale": "tr",
  "conversationId": "23233333",
  "cardUserKey": "6abd3f19-8305-d0c9-09e2-0300b5516a38"
}
{
  "status": "success",
  "locale": "tr",
  "systemTime": 1756307234300,
  "conversationId": "23233333",
  "cardUserKey": "7f4be1bd-1f46-3425-f2ea-3a9ecd70f182",
  "cardDetails": [
    {
      "cardToken": "dc9f677b-d658-7458-0b7f-a0fccdb05019",
      "cardAlias": "card_alias",
      "binNumber": "55260800",
      "lastFourDigits": "0006",
      "cardType": "CREDIT_CARD",
      "cardAssociation": "MASTER_CARD",
      "cardFamily": "Axess",
      "cardBankCode": 46,
      "cardBankName": "Akbank",
      "expireMonth": "12",
      "expireYear": "2033"
    }
  ]
}

Saklı Kart ile Ödeme Alma (NON3D)

post

Kart saklama işlemi sonrasında tarafınıza dönen cardUserKey ve cardToken bilgisini kullanarak “NON3D veya 3DS” ödeme isteği gönderebilirsiniz. Standart ödeme isteğinden farklı olarak kart bilgileri yine cardUserKey ve cardToken değeri gönderilmektedir. Tek tık ile ödeme kolaylığı sağlamak isteyen veya abonelik döngüsü oluşturmak isteyen üye işyerleri tarafında kullanılabilir. Aşağıda NON3D örneği paylaşılmaktadır.

Header parameters
AuthorizationstringRequired

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

Content-TypestringRequired

İstek gövdesinin veri formatı.

Example: application/json
Body

Saklı kart kullanarak NON3D ödeme alma isteği.

localestring · enumOptional

Dil kodu. Alabileceği değerler; tr, en. Default; tr

Example: trPossible values:
conversationIdstringOptional

İstek/yanıt eşleştirmesi için benzersiz ID.

Example: conversationId
paidPricedecimalRequired

Kullanıcıdan tahsil edilecek toplam tutar.

Example: 1
pricedecimalRequired

Sepet toplam tutarı.

Example: 1
installmentinteger · enumOptional

Taksit sayısı. Gönderilmezse tek çekim (1) olarak işlem sağlanır.

Example: 1Possible values:
paymentChannelstring · enumOptional

Ödeme kanalı.

Example: WEBPossible values:
basketIdstringOptional

Sepet ID’si.

Example: B67832
paymentGroupstring · enumOptional

Ödeme grubu. Default; PRODUCT.

Example: PRODUCTPossible values:
currencystring · enumOptional

Para birimi. Default; TRY.

Example: TRYPossible values:
Responses
200

Başarılı yanıt — ödeme alındı

application/json

Standart yanıt alanları.

statusstring · enumOptional

Yapılan isteğin sonucunu bildirir.

Example: successPossible values:
localestringOptional

Yanıt dili (tr/en).

Example: tr
systemTimeintegerOptional

İşlem zamanı (epoch ms).

Example: 1755198001941
conversationIdstringOptional

İstek esnasında gönderilmişse, yanıtta aynen geri iletilir.

Example: conversationId
pricedecimalOptional

Sepet toplam tutarı.

Example: 1
paidPricedecimalOptional

Tahsil edilen toplam tutar.

Example: 1
installmentintegerOptional

Taksit sayısı.

Example: 1
paymentIdstringOptional

Ödeme ID’si.

Example: 25149157
fraudStatusinteger · enumOptional

Fraud filtrelerine göre ödeme durumu. Eğer ödemenin fraud risk skoru düşük ise ödemeye anında onay verilir, eğer fraud risk skoru yüksek ise ödeme işlemi reddedilir. Üye işyeri sadece 1 olan işlemlerde ürünü kargoya vermelidir, 0 olan işlemler için bilgilendirme beklemelidir.

  • 1: Onaylandı
  • 0: İncelemede
  • -1: Reddedildi
Example: 1Possible values:
merchantCommissionRatedecimalOptional

Üye işyerinin uyguladığı vade/komisyon oranı. Örneğin price=100, paidPrice=110 ise üye işyeri vade/komisyon oranı %10’dur. Bilgi amaçlıdır.

Example: 10
merchantCommissionRateAmountdecimalOptional

Üye işyerinin uyguladığı vade/komisyon tutarı. Örneğin price=100, paidPrice=110 ise üye işyeri vade/komisyon tutarı 10’dur. Bilgi amaçlıdır.

Example: 0.1
iyziCommissionRateAmountdecimalOptional

iyzico komisyon oran tutarı.

Example: 0.03839
iyziCommissionFeedecimalOptional

Ödemeye ait iyzico işlem ücreti.

Example: 0.25
cardTypestring · enumOptional

Kart tipi.

Example: CREDIT_CARDPossible values:
cardAssociationstring · enumOptional

Kart kuruluşu.

Example: MASTER_CARDPossible values:
cardFamilystring · enumOptional

Kart ailesi.

Example: AxessPossible values:
binNumberstringOptional

BIN (ilk 8 hane).

Example: 552608
lastFourDigitsstringOptional

Kartın son 4 hanesi.

Example: 0006
basketIdstringOptional

Sepet ID.

Example: B67832
currencystring · enumOptionalExample: TRYPossible values:
authCodestringOptional

Ödeme Fazı.

Example: 526832
phasestringOptionalExample: AUTH
hostReferencestringOptional

Ödemeye ilişkin banka tarafından verilen hostReference değeri.

Example: mock00007iyzihostrfn
signaturestringOptional

İmza doğrulaması için kullanılabilecek signature değeri.

Example: 03d01d123540295e0658e6400f096fbd346791df3838e6644740121db937e182
post/payment/auth
POST https://api.iyzipay.com/payment/auth
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "tr",
  "conversationId": "123456789",
  "price": 1.0,
  "paidPrice": 1.1,
  "installment": 1,
  "paymentChannel": "WEB",
  "basketId": "B67832",
  "paymentGroup": "LISTING",
  "currency": "TRY",
  "paymentCard": {
    "cardUserKey": "7f4be1bd-1f46-3425-f2ea-3a9ecd70f182",
    "cardToken": "dc9f677b-d658-7458-0b7f-a0fccdb05019"
  },
  "buyer": {
    "id": "BY789",
    "name": "John",
    "surname": "Doe",
    "identityNumber": "74300864791",
    "email": "email@email.com",
    "gsmNumber": "+905350000000",
    "registrationDate": "2013-04-21 15:12:09",
    "lastLoginDate": "2015-10-05 12:43:35",
    "registrationAddress": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "city": "Istanbul",
    "country": "Turkey",
    "zipCode": "34732",
    "ip": "85.34.78.112"
  },
  "shippingAddress": {
    "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "zipCode": "34742",
    "contactName": "Jane Doe",
    "city": "Istanbul",
    "country": "Turkey"
  },
  "billingAddress": {
    "address": "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
    "contactName": "Jane Doe",
    "city": "Istanbul",
    "country": "Turkey"
  },
  "basketItems": [
    {
      "id": "BI101",
      "price": 1,
      "name": "Binocular",
      "category1": "Collectibles",
      "category2": "Accessories",
      "itemType": "PHYSICAL"
    }
  ]
}

{
  "status": "success",
  "locale": "tr",
  "systemTime": 1756309795470,
  "conversationId": "123456789",
  "price": 1,
  "paidPrice": 1.1,
  "installment": 1,
  "paymentId": "25232429",
  "fraudStatus": 1,
  "merchantCommissionRate": 10,
  "merchantCommissionRateAmount": 0.1,
  "iyziCommissionRateAmount": 0.03839,
  "iyziCommissionFee": 0.25,
  "cardType": "CREDIT_CARD",
  "cardAssociation": "MASTER_CARD",
  "cardFamily": "Axess",
  "binNumber": "552608",
  "lastFourDigits": "0006",
  "basketId": "B67832",
  "currency": "TRY",
  "itemTransactions": [
    {
      "itemId": "BI101",
      "paymentTransactionId": "27221602",
      "transactionStatus": 2,
      "price": 1,
      "paidPrice": 1.1,
      "merchantCommissionRate": 10,
      "merchantCommissionRateAmount": 0.1,
      "iyziCommissionRateAmount": 0.03839,
      "iyziCommissionFee": 0.25,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-09-03 18:49:55",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 0.81161,
      "convertedPayout": {
        "paidPrice": 1.1,
        "iyziCommissionRateAmount": 0.03839,
        "iyziCommissionFee": 0.25,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 0.81161,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    }
  ],
  "authCode": "526832",
  "phase": "AUTH",
  "hostReference": "mock00007iyzihostrfn",
  "signature": "03d01d123540295e0658e6400f096fbd346791df3838e6644740121db937e182"
}

Saklı Kart Silme

delete

iyzico'da oluşturulan bir kullanıcıya ait bir kartı siler.

Header parameters
AuthorizationstringRequired

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

Content-TypestringRequired

İstek gövdesinin veri formatı.

Example: application/json
Body

Saklı kartı silme isteği.

localestringOptional

Yanıt dilini belirler. Varsayılan tr.

Example: tr
conversationIdstringOptional

İstek/yanıt eşleşmesi için gönderilen ID.

Example: 123456789
cardUserKeystringRequired

Kartın bağlı olduğu kullanıcı anahtarı.

Example: 6abd3f19-8305-d0c9-09e2-0300b5516a38
cardTokenstringRequired

Silinecek kartın token değeri.

Example: c80ba376-8250-f819-88c9-94984710e72c
Responses
200

Başarılı yanıt

application/json

Standart yanıt alanları.

statusstring · enumOptional

Yapılan isteğin sonucunu bildirir.

Example: successPossible values:
localestringOptional

Yanıt dili (tr/en).

Example: tr
systemTimeintegerOptional

İşlem zamanı (epoch ms).

Example: 1755198001941
conversationIdstringOptional

İstek esnasında gönderilmişse, yanıtta aynen geri iletilir.

Example: conversationId
pricedecimalOptional

Sepet toplam tutarı.

Example: 1
paidPricedecimalOptional

Tahsil edilen toplam tutar.

Example: 1
installmentintegerOptional

Taksit sayısı.

Example: 1
paymentIdstringOptional

Ödeme ID’si.

Example: 25149157
fraudStatusinteger · enumOptional

Fraud filtrelerine göre ödeme durumu. Eğer ödemenin fraud risk skoru düşük ise ödemeye anında onay verilir, eğer fraud risk skoru yüksek ise ödeme işlemi reddedilir. Üye işyeri sadece 1 olan işlemlerde ürünü kargoya vermelidir, 0 olan işlemler için bilgilendirme beklemelidir.

  • 1: Onaylandı
  • 0: İncelemede
  • -1: Reddedildi
Example: 1Possible values:
merchantCommissionRatedecimalOptional

Üye işyerinin uyguladığı vade/komisyon oranı. Örneğin price=100, paidPrice=110 ise üye işyeri vade/komisyon oranı %10’dur. Bilgi amaçlıdır.

Example: 10
merchantCommissionRateAmountdecimalOptional

Üye işyerinin uyguladığı vade/komisyon tutarı. Örneğin price=100, paidPrice=110 ise üye işyeri vade/komisyon tutarı 10’dur. Bilgi amaçlıdır.

Example: 0.1
iyziCommissionRateAmountdecimalOptional

iyzico komisyon oran tutarı.

Example: 0.03839
iyziCommissionFeedecimalOptional

Ödemeye ait iyzico işlem ücreti.

Example: 0.25
cardTypestring · enumOptional

Kart tipi.

Example: CREDIT_CARDPossible values:
cardAssociationstring · enumOptional

Kart kuruluşu.

Example: MASTER_CARDPossible values:
cardFamilystring · enumOptional

Kart ailesi.

Example: AxessPossible values:
binNumberstringOptional

BIN (ilk 8 hane).

Example: 552608
lastFourDigitsstringOptional

Kartın son 4 hanesi.

Example: 0006
basketIdstringOptional

Sepet ID.

Example: B67832
currencystring · enumOptionalExample: TRYPossible values:
authCodestringOptional

Ödeme Fazı.

Example: 526832
phasestringOptionalExample: AUTH
hostReferencestringOptional

Ödemeye ilişkin banka tarafından verilen hostReference değeri.

Example: mock00007iyzihostrfn
signaturestringOptional

İmza doğrulaması için kullanılabilecek signature değeri.

Example: 03d01d123540295e0658e6400f096fbd346791df3838e6644740121db937e182
delete/cardstorage/card
DELETE https://api.iyzipay.com/cardstorage/card
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "tr",
  "conversationId": "123456789",
  "cardUserKey": "6abd3f19-8305-d0c9-09e2-0300b5516a38",
  "cardToken": "c80ba376-8250-f819-88c9-94984710e72c"
}

{
  "status": "success",
  "locale": "tr",
  "systemTime": 1756308913460,
  "conversationId": "123456789"
}

Last updated