API - 3DS

Initialize 3DS Payment

post

3D Secure oturumu başlatır ve 3DS doğrulama için htmlContent değeri döner.

Header parameters

AuthorizationstringRequired

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

Example: IYZWSv2 aXBzaWduYXR1cmU...

Content-TypestringRequired

Content-Type değeri.

Example: application/json

Body

application/json

localestring · enumOptional

Dil kodu. Varsayılan; tr

Example: trPossible values:

conversationIdstringOptional

İstek/yanıt eşleştirme ID’si.

Example: conversationId

pricedecimalRequired

Sepet toplamı.

Example: 1

paidPricedecimalRequired

Tahsil edilecek nihai tutar.

Example: 1

currencystring · enumOptional

Para birimi. Varsayılan; TRY.

Example: TRYPossible values:

installmentinteger · enumOptional

Taksit sayısı (gönderilmezse tek çekim olarak işlem gerçekleşir).

Example: 1Possible values:

paymentChannelstring · enumOptional

Ödeme kanalı.

Example: WEBPossible values:

basketIdstringOptional

Sepet ID.

Example: basketId

paymentGroupstring · enumOptional

Ödeme grubu. Varsayılan; PRODUCT.

Example: PRODUCTPossible values:

callbackUrlstringRequired

3DS işlem sonrası yönlenecek dönüş URL’si.

Example: https://callbackurl.com

paymentSourcestringOptional

Bu alan, partner firmalar tarafından iletilen ödeme kaynağı bilgisidir. Eğer bir altyapı sağlayıcısıysanız ve iyzico ile entegrasyon/iş birliğiniz bulunuyorsa bu parametreyi gönderebilirsiniz.

Example: Shopify

Responses

200

Başarılı yanıt (3DS başlatıldı)

application/json

400

Hatalı istek / doğrulama hatası

application/json

post

/payment/3dsecure/initialize

HTTP

POST https://api.iyzipay.com/payment/3dsecure/initialize
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "tr",
  "conversationId": "conversationId",
  "price": 1.0,
  "paidPrice": 1.0,
  "currency": "TRY",
  "installment": 1,
  "paymentChannel": "WEB",
  "basketId": "basketId",
  "paymentGroup": "PRODUCT",
  "callbackUrl": "callbackUrl",
  "paymentCard": {
    "cardHolderName": "John Doe",
    "cardNumber": "5528790000000008",
    "expireYear": "28",
    "expireMonth": "12",
    "cvc": "123",
    "registerCard":0
  },
  "buyer": {
    "id": "1",
    "name": "John",
    "surname": "Doe",
    "identityNumber": "1234512345123125213125213",
    "email": "[email protected]",
    "gsmNumber": "[phone]",
    "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": "İstanbul",
    "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": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "zipCode": "34742",
    "contactName": "Jane Doe",
    "city": "Istanbul",
    "country": "Turkey"
  },
  "basketItems": [
    { "id": "BI101", "price": 0.4, "name": "Binocular", "category1": "Collectibles", "category2": "Accessories", "itemType": "PHYSICAL" },
    { "id": "BI102", "price": 0.3, "name": "Game code", "category1": "Game", "category2": "Online Game Items", "itemType": "VIRTUAL" },
    { "id": "BI103", "price": 0.3, "name": "Usb", "category1": "Electronics", "category2": "Usb / Cable", "itemType": "PHYSICAL" }
  ],
  "paymentSource": "Test"
}

{
  "status": "success",
  "locale": "tr",
  "systemTime": 1755197726218,
  "conversationId": "conversationId",
  "threeDSHtmlContent": "PCFkb2N0eXBlIGh0bWw+...",
  "paymentId": "25149157",
  "signature": "c8964a1878f9dae20741209dea6749d16bac4a8760775ae69b0b2420d9dc024b"
}

Create 3DS Payment

post

3DS doğrulaması sonrasında, ödeme işleminin sonlandırılması için bu endpoint’e istek yapılmalıdır. Bu servis, doğrulama adımından sonra alınan bilgilerle çalıştırılır ve işlemi başarılı ya da başarısız olarak sonuçlandırır.

Header parameters

AuthorizationstringRequired

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

Example: IYZWSv2 aXBzaWduYXR1cmU...

Content-TypestringRequired

Content-Type değeri.

Example: application/json

Body

application/json

localestring · enumOptional

Dil kodu. Varsayılan; tr

Example: trPossible values:

paymentIdstringRequired

Initialize çağrısından dönen ödeme ID’si.

Example: 25149157

conversationIdstringOptional

İstek/yanıt eşleştirme ID’si.

Example: conversationId

conversationDatastringOptional

3DS sonucunda post edilen data. Dolu dönerse gönderilmesi zorunludur.

Responses

200

Başarılı yanıt (ödeme tamamlandı)

application/json

400

Hatalı istek / doğrulama hatası

application/json

post

/payment/3dsecure/auth

HTTP

POST https://api.iyzipay.com/payment/3dsecure/auth
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "tr",
  "paymentId": "25149157",
  "conversationId": "conversationId",
  "conversationData": ""
}

{
  "status": "success",
  "locale": "tr",
  "systemTime": 1755198001941,
  "conversationId": "conversationId",
  "price": 1,
  "paidPrice": 1,
  "installment": 1,
  "paymentId": "25149157",
  "fraudStatus": 1,
  "merchantCommissionRate": 0,
  "merchantCommissionRateAmount": 0,
  "iyziCommissionRateAmount": 0.0349,
  "iyziCommissionFee": 0.25,
  "cardType": "CREDIT_CARD",
  "cardAssociation": "MASTER_CARD",
  "cardFamily": "Paraf",
  "binNumber": "552879",
  "lastFourDigits": "0008",
  "basketId": "basketId",
  "currency": "TRY",
  "itemTransactions": [
    {
      "itemId": "BI101",
      "paymentTransactionId": "27138714",
      "transactionStatus": 2,
      "price": 0.4,
      "paidPrice": 0.4,
      "merchantCommissionRate": 0,
      "merchantCommissionRateAmount": 0,
      "iyziCommissionRateAmount": 0.01396,
      "iyziCommissionFee": 0.1,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-08-22 00:00:00",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 0.28604,
      "convertedPayout": {
        "paidPrice": 0.4,
        "iyziCommissionRateAmount": 0.01396,
        "iyziCommissionFee": 0.1,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 0.28604,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    },
    {
      "itemId": "BI102",
      "paymentTransactionId": "27138715",
      "transactionStatus": 2,
      "price": 0.3,
      "paidPrice": 0.3,
      "merchantCommissionRate": 0,
      "merchantCommissionRateAmount": 0,
      "iyziCommissionRateAmount": 0.01047,
      "iyziCommissionFee": 0.075,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-08-22 00:00:00",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 0.21453,
      "convertedPayout": {
        "paidPrice": 0.3,
        "iyziCommissionRateAmount": 0.01047,
        "iyziCommissionFee": 0.075,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 0.21453,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    },
    {
      "itemId": "BI103",
      "paymentTransactionId": "27138716",
      "transactionStatus": 2,
      "price": 0.3,
      "paidPrice": 0.3,
      "merchantCommissionRate": 0,
      "merchantCommissionRateAmount": 0,
      "iyziCommissionRateAmount": 0.01047,
      "iyziCommissionFee": 0.075,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-08-22 00:00:00",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 0.21453,
      "convertedPayout": {
        "paidPrice": 0.3,
        "iyziCommissionRateAmount": 0.01047,
        "iyziCommissionFee": 0.075,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 0.21453,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    }
  ],
  "authCode": "214525",
  "phase": "AUTH",
  "mdStatus": 1,
  "hostReference": "mock00001iyzihostrfn",
  "signature": "5f510cd92b4b9c50a39b617cda228f4159f290860a4c20a965c55b119c9e9052"
}

Create 3DS v2 Payment

post

Doğrulama sonrası ödeme sonucunun alınması için hem v1 hem de yeni nesil v2 endpoint’i kullanılabilir. Daha güncel teknolojilere uyum sağlamak adına v2 endpoint’inin kullanılmasını öneririz.

Header parameters

AuthorizationstringRequired

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

Example: IYZWSv2 aXBzaWduYXR1cmU...

Content-TypestringRequired

Content-Type değeri.

Example: application/json

Body

application/json

localestring · enumOptional

Dil kodu. Varsayılan; tr

Example: trPossible values:

paymentIdstringRequired

3DS başlatma sonrasında dönen ödeme ID’si.

Example: 25146302

conversationIdstringOptional

İstek/yanıt eşleştirme ID’si.

Example: conversationId

paidPricedecimalRequired

3DS v2 tamamlamada kullanılacak tahsilat tutarı. INIT 3DS aşamasında gönderilen paidPrice değeri ile uyumlu olmalı.

Example: 1

basketIdstringRequired

Sepet ID’si (INIT 3DS basketId ile eşleşmelidir).

Example: basketId

currencystring · enumRequired

Para birimi. Varsayılan; TRY (INIT 3DS'de gönderilen değer ile eşleşmelidir.)

Example: TRYPossible values:

Responses

200

Başarılı yanıt (ödeme tamamlandı)

application/json

400

Hatalı istek / doğrulama hatası

application/json

post

/payment/v2/3dsecure/auth

HTTP

POST https://api.iyzipay.com/payment/v2/3dsecure/auth
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "tr",
  "paymentId": "25146302",
  "conversationId": "conversationId",
  "paidPrice": 1.0,
  "basketId": "basketId",
  "currency": "TRY"
}

{
  "status": "success",
  "locale": "tr",
  "systemTime": 1755203584577,
  "conversationId": "conversationId",
  "price": 1,
  "paidPrice": 1,
  "installment": 1,
  "paymentId": "25149538",
  "fraudStatus": 1,
  "merchantCommissionRate": 0,
  "merchantCommissionRateAmount": 0,
  "iyziCommissionRateAmount": 0.0349,
  "iyziCommissionFee": 0.25,
  "cardType": "CREDIT_CARD",
  "cardAssociation": "MASTER_CARD",
  "cardFamily": "Paraf",
  "binNumber": "552879",
  "lastFourDigits": "0008",
  "basketId": "basketId",
  "currency": "TRY",
  "paymentChannel": "WEB",
  "itemTransactions": [
    {
      "itemId": "BI101",
      "paymentTransactionId": "27139066",
      "transactionStatus": 2,
      "price": 0.4,
      "paidPrice": 0.4,
      "merchantCommissionRate": 0,
      "merchantCommissionRateAmount": 0,
      "iyziCommissionRateAmount": 0.01396,
      "iyziCommissionFee": 0.1,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-08-22 00:00:00",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 0.28604,
      "convertedPayout": {
        "paidPrice": 0.4,
        "iyziCommissionRateAmount": 0.01396,
        "iyziCommissionFee": 0.1,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 0.28604,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    }
  ],
  "authCode": "847162",
  "phase": "AUTH",
  "mdStatus": 1,
  "hostReference": "mock00001iyzihostrfn",
  "signature": "f95c9246235c30cad41169bb1df7381b7ffe42bf1ea1226c2dd211e83dfe40f7"
}