3DS Tamamlama

xiyzico'da kayıtlı bir işlemin detayına ulaşmak için ödeme sorgulama hizmetini kullanabilirsiniz.

Servise gönderilmesi gereken parametreler aşağıdaki gibidir:

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

statusstring · enumOptional

Yapılan işleminin sonucunu bildirir. success dönmesi taktirinde ödeme işlemi başarılı anlamına gelir.

Example: successPossible values:

localestringOptional

Yanıt dili (tr/en).

Example: tr

systemTimeintegerOptional

İşlem zamanı (epoch ms).

Example: 1755198001941

conversationIdstringOptional

İstek ile eşleşen ID.

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: 0

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

iyziCommissionRateAmountdecimalOptional

Ödemeye ait iyzico işlem komisyon tutarı.

Example: 0.2094

iyziCommissionFeedecimalOptional

Ödemeye ait iyzico işlem ücreti.

Example: 0.25

cardTypestringOptional

Kart tipi.

Example: CREDIT_CARD

cardAssociationstring · enumOptional

Kart markası.

Example: MASTER_CARDPossible values:

cardFamilystringOptional

Kart ailesi/ürünü.

Example: Axess

binNumberstringOptional

BIN (ilk 8 hane).

Example: 552608

lastFourDigitsstringOptional

Kartın son 4 hanesi.

Example: 0006

basketIdstringOptional

Sepet ID.

Example: basketId

currencystringOptional

Para birimi.

Example: TRY

authCodestringOptional

Bankadan dönen authCode değeri.

Example: 214525

phasestringOptional

Ödeme Fazı.

Example: AUTH

mdStatusinteger · enumOptional

3DS doğrulama sonucu (1 ise başarılı).

Example: 1Possible values:

hostReferencestringOptional

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

Example: mock00001iyzihostrfn

signaturestringOptional

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

Example: 5f510cd92b4b9c50a39b617cda228f4159f290860a4c20a965c55b119c9e9052

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"
}

Örnek Kodlar

PHP

Java

.NET

Node.Js

Python

Postman

3DS Tamamlama v2 - Geliştirilmiş Ödeme Güvenliği

iyzico'da, yakın zamanda gerçekleştirilen HMACSHA256 güncellemesinin ardından, mevcut payment/v2/3dsecure/auth endpoint’ine ek olarak payment/3dsecure/auth endpoint'ini devreye aldık. Bu endpoint, kayıtlı 3D ödemelerini tamamlamak ve müşterinin kartından çekilen nihai tutar, ilgili ödemenin conversationId ve paymentId bilgilerini içeren detayları elde etmek için kullanılır.

Bununla birlikte, ilgili ödemenin tamamlanması için daha güvenilir doğrulama teknikleri kullanılabilir. İmza Yanıtının Doğrulanması'nda belirtildiği gibi, ödeme isteği sonucunda döndürülen ve istek tablosunda listelenen değişkenler bu süreçte önemli bir rol oynar.

İmza Yanıtının Doğrulanması'nda gösterildiği gibi, şifrelenmiş payload için her iki tarafta imza üretildiğinde ve bu imzalar eşit olduğunda, ilgili ödeme başarıyla tamamlanır.

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

statusstring · enumOptional

Yapılan isteğin sonucunu bildirir. success dönmesi taktirinde, ödeme işlemi başarılı olduğu anlamına gelir.

Example: successPossible values:

localestring · enumOptional

Yanıt dili.

Example: trPossible values:

systemTimeintegerOptional

Zaman damgası (epoch ms).

Example: 1755203584577

conversationIdstringOptional

İstek ile eşleşen ID.

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: 25149538

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: 0

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

iyziCommissionRateAmountdecimalOptional

Ödemeye ait iyzico işlem komisyon tutarı.

Example: 0.2094

iyziCommissionFeedecimalOptional

Ödemeye ait iyzico işlem ücreti.

Example: 0.25

cardTypestringOptional

Kart tipi.

Example: CREDIT_CARD

cardAssociationstring · enumOptional

Kart kuruluşu.

Example: MASTER_CARDPossible values:

cardFamilystringOptional

Kart ailesi/ürünü.

Example: Axess

binNumberstringOptional

BIN (ilk 8 hane).

Example: 552608

lastFourDigitsstringOptional

Kartın son 4 hanesi.

Example: 0006

basketIdstringOptional

Sepet ID.

Example: basketId

currencystringOptional

Para birimi.

Example: TRY

authCodestringOptional

Bankadan dönen authCode değeri.

Example: 847162

phasestringOptional

Ödeme Fazı.

Example: AUTH

mdStatusinteger · enumOptional

3DS doğrulama sonucu.

• 1: Başarılı
• 0,2-8: Başarısız

Example: 1Possible values:

hostReferencestringOptional

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

Example: mock00001iyzihostrfn

signaturestringOptional

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

Example: f95c9246235c30cad41169bb1df7381b7ffe42bf1ea1226c2dd211e83dfe40f7

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"
}

Örnek Kodlar

Java

Json

Auth 3DS vs Auth v2 3DS

Daha önce geliştirilmiş olan payment/3dsecure/auth endpoint’i, standart 3D Secure 1.0 protokolünü kullanır ve daha basit bir yapı sunarak eski sistemlerin entegrasyonunu kolaylaştırır. Buna karşılık, payment/v2/3dsecure/auth endpointendpoint’i, daha gelişmiş 3D Secure 2.0 protokolü üzerine inşa edilmiştir. Bu yeni protokol, risk analizi için daha zengin veri noktaları sunarak güvenliği artırır ve modern sistemlerle daha akıcı bir entegrasyon sağlar. payment/3dsecure/auth istemel işlemler için güvenilir bir seçenek olsa da, payment/v2/3dsecure/auth daha üstün güvenlik, geliştirilmiş kullanıcı deneyimi ve gelişen ödeme düzenlemeleriyle daha iyi uyumluluk sunar. Bu avantajlar için payment/v2/3dsecure/auth geçiş yapmanızı öneririz.