3DS Tamamlama

iyzico'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:

3DS Tamamlama

POST https://api.iyzipay.com/payment/3dsecure/auth

Request Body

Name	Type	Description
locale	String	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	İ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 sipariş numarasıdır.
paymentId*	String	3D dönüş bağlantı adresinizden alacağınız paymentid değeridir.
conversationData*	String	3D dönüş bağlantı adresinizden alacağınız conversationData değeridir. Bu parametre bir değer ile dönüş yapmış ise 3D ödeme sorgusunda eklenmelidir.

200: OK

{
    "status": "success",
    "locale": "tr",
    "systemTime": 1685539637584,
    "price": 3.20000000,
    "paidPrice": 3.20000000,
    "installment": 1,
    "paymentId": "123456789",
    "fraudStatus": 1,
    "merchantCommissionRate": 0E-8,
    "merchantCommissionRateAmount": 0E-8,
    "iyziCommissionRateAmount": 0.12800000,
    "iyziCommissionFee": 0.25000000,
    "cardType": "DEBIT_CARD",
    "cardAssociation": "MASTER_CARD",
    "cardFamilyName": "iyzico DC",
    "binNumber": "535805",
    "lastFourDigits": "0006",
    "basketId": "B67832",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "123456789",
            "transactionStatus": 2,
            "price": 1.10000000,
            "paidPrice": 1.10000000,
            "merchantCommissionRate": 0E-8,
            "merchantCommissionRateAmount": 0E-8,
            "iyziCommissionRateAmount": 0.04400000,
            "iyziCommissionFee": 0.08593750,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0,
            "blockageResolvedDate": "2023-06-08 00:00:00",
            "subMerchantPrice": 0,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0,
            "merchantPayoutAmount": 0.97006250,
            "convertedPayout": {
                "paidPrice": 1.10000000,
                "iyziCommissionRateAmount": 0.04400000,
                "iyziCommissionFee": 0.08593750,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 0.97006250,
                "iyziConversionRate": 0,
                "iyziConversionRateAmount": 0,
                "currency": "TRY"
            }
        },
        {
            "itemId": "BI1012",
            "paymentTransactionId": "123456788",
            "transactionStatus": 2,
            "price": 2.10000000,
            "paidPrice": 2.10000000,
            "merchantCommissionRate": 0E-8,
            "merchantCommissionRateAmount": 0E-8,
            "iyziCommissionRateAmount": 0.08400000,
            "iyziCommissionFee": 0.16406250,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0,
            "blockageResolvedDate": "2023-06-08 00:00:00",
            "subMerchantPrice": 0,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0,
            "merchantPayoutAmount": 1.85193750,
            "convertedPayout": {
                "paidPrice": 2.10000000,
                "iyziCommissionRateAmount": 0.08400000,
                "iyziCommissionFee": 0.16406250,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 1.85193750,
                "iyziConversionRate": 0,
                "iyziConversionRateAmount": 0,
                "currency": "TRY"
            }
        }
    ],
    "authCode": "905307",
    "phase": "AUTH",
    "mdStatus": 1,
    "hostReference": "mock00007iyzihostrfn"
}

3DS Tamamlama Dönen Parametreler

Parametre İsmi	Veri Tipi	Açıklama
status	String	Yapılan isteğin sonucunu bildirir. İşlem başarılı ise success, hatalı ise failure döner.
errorCode	String	İşlem hatalıysa, bu hataya dair belirtilen koddur.
errorMessage	String	İşlem hatalıysa, bu hataya dair belirtilen mesajdır. Locale parametresine göre dil desteği sunar.
errorGroup	String	İşlem hatalıysa, bu hataya dair belirtilen gruptur.
locale	String	İstekte belirtilen locale değeri geri dönülür, varsayılan değeri tr’dir.
systemTime	Long	Dönen sonucun o anki unix timestamp değeridir.
conversationId	String	İstek esnasında gönderilmişse, sonuçta aynen geri iletilir.
paymentId	String	Ödemeye ait id, üye işyeri tarafından mutlaka saklanmalıdır. Ödemenin iptali ve iyzico ile iletişimde kullanılır.
price	Decimal	Ödeme sepet tutarı. Kırılım tutarlar toplamı sepet tutarına eşit olmalı.
paidPrice	Decimal	İndirim vade farkı vs. hesaplanmış POS’tan geçen, tahsil edilen, nihai tutar.
currency	String	Ödemenin alındığı para birimi.
installment	Integer	Ödemenin taksit bilgisi, tek çekim için 1 döner. Geçerli değerler: 1, 2, 3, 6, 9, 12.
paymentStatus	String	İşlemin sonucunu gösterir. Geçerli değerler SUCCESS, FAILURE, INIT_THREEDS, CALLBACK_THREEDS, BKM_POS_SELECTED, CALLBACK_PECCO
basketId	String	Üye işyeri tarafından gönderilen sepet id’si.
binNumber	String	Ödeme yapılan kartın ilk 6 hanesi.
cardAssociation	String	Eğer ödeme yapılan kart yerel bir kart ise, kartın ait olduğu kuruluş. Geçerli değerler: VISA, MASTER_CARD, AMERICAN_EXPRESS, TROY
cardFamily	String	Eğer ödeme yapılan kart yerel bir kart ise, kartın ait olduğu aile. Geçerli değerler: Bonus, Axess, World, Maximum, Paraf, CardFinans, Advantage
cardType	String	Eğer ödeme yapılan kart yerel bir kart ise, kartın ait olduğu tipi. Geçerli değerler: CREDIT_CARD, DEBIT_CARD, PREPAID_CARD
fraudStatus	Integer	Ödeme işleminin fraud filtrelerine göre durumu. Eğer ödemenin fraud risk skoru düşük ise ödemeye anında onay verilir, bu durumda 1 değeri döner. Eğer fraud risk skoru yüksek ise ödeme işlemi reddedilir ve -1 döner. Eğer ödeme işlemi daha sonradan incelenip karar verilecekse 0 döner. Geçerli değerler: 0, -1 ve 1. Üye işyeri sadece 1 olan işlemlerde ürünü kargoya vermelidir, 0 olan işlemler için bilgilendirme beklemelidir.
iyziCommissionFee	Decimal	Ödemeye ait iyzico işlem ücreti.
iyziCommissionRateAmount	Decimal	Ödemeye ait iyzico işlem komisyon tutarı.
merchantCommissionRate	Decimal	Ü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.
merchantCommissionRateAmount	Decimal	Ü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.
paymentTransactionId (ItemTransactions)	String	Ödeme kırılımına ait id, üye işyeri tarafından mutlaka saklanmalıdır. Ödeme kırılımının iadesi, onayı, onay geri çekmesi ve iyzico ile iletişimde kullanılır. Tercihen itemId ile ilişkili bir şekilde tutulmalıdır.
itemId(ItemTransactions)	String	Üye işyeri tarafından iletilen, sepetteki ürüne ait id.
price(ItemTransactions)	Decimal	Üye işyeri tarafındaki sepetteki ürüne ait tutar.
paidPrice(ItemTransactions)	Decimal	Tahsilat tutarının kırılım bazındaki dağılımı. Üye işyeri tarafından mutlaka saklanmalıdır.
transactionStatus (ItemTransactions)	Integer	Ödeme kırılımının durumu. Ödeme fraud kontrolünde ise 0 değeri döner, bu durumda fraudStatus değeri de 0’dır. Ödeme, fraud kontrolünden sonra reddedilirse -1 döner. Pazaryeri modelinde ürüne onay verilene dek bu değer 1 olarak döner. Pazaryeri modelinde ürüne onay verilmişse bu değer 2 olur. Geçerli değerler: 0, -1, 1, 2.
blockageRate(ItemTransactions)	Decimal	Kırılım bazında üye işyeri blokaj oranı. iyzico – üye işyeri anlaşmasına göre, üye işyerine işlem bazında blokaj uygulayabilir. Bu blokaj üye işyeri fraud riskini önlemek içindir, blokaj süresi boyunca para iyzico’da tutulur, bu süre sonrasında üye işyerine gönderilir.
blockageRateAmountMerchant(ItemTransactions)	Decimal	Kırılım bazında üye işyeri blokaj tutarının, üye işyerine yansıyan rakamı. Blokaj tutarı mümkün olduğunca üye işyerine yansıtılır. Eğer blokaj tutarı, üye işyeri tutarından daha büyükse bu durumda alt üye işyerine de yansıtılır.
blockageResolvedDate(ItemTransactions)	String	İşlem bazında blokaj çözülme tarihi. yyyy-MM-dd HH:mm:ss formatındadır, örneğin 2015-10-19 14:36:52.
iyziCommissionFee(ItemTransactions)	Decimal	iyzico işlem ücretinin kırılım bazında dağılmış tutarı.
iyziCommissionRateAmount(ItemTransactions)	Decimal	iyzico işlem komisyon tutarının kırılım bazında dağılmış tutarı.
merchantCommissionRate(ItemTransactions)	Decimal	Üye işyerinin uyguladığı vade/komisyon oranının kırılım bazında dağılmış oranı.
merchantCommissionRateAmount(ItemTransactions)	Decimal	Üye işyerinin uyguladığı vade/komisyon tutarıın, kırılım bazında dağılmış tutarı.
merchantPayoutAmount(ItemTransactions)	Decimal	Bu kırılım için, iyzico işlem ücreti, komisyon tutarı ve blokajlar düşüldükten sonra üye işyerine gönderilecek tutar.
paidPrice(ItemTransactions)(convertedPayout)	Decimal	Tahsilat tutarının kırılım bazındaki dağılımı. Üye işyeri tarafından mutlaka saklanmalıdır.
iyziCommissionFee(ItemTransactions)(convertedPayout)	Decimal	iyzico işlem ücretinin kırılım bazında dağılmış tutarı.
iyziCommissionRateAmount(ItemTransactions)(convertedPayout)	Decimal	iyzico işlem komisyon tutarının kırılım bazında dağılmış tutarı.
blockageRateAmountMerchant(ItemTransactions)(convertedPayout)	Decimal	Kırılım bazında üye işyeri blokaj tutarının, üye işyerine yansıyan rakamı. Blokaj tutarı mümkün olduğunca üye işyerine yansıtılır. Eğer blokaj tutarı, üye işyeri tutarından daha büyükse bu durumda alt üye işyerine de yansıtılır.
merchantPayoutAmount(ItemTransactions)(convertedPayout)	Decimal	Bu kırılım için, iyzico işlem ücreti, komisyon tutarı ve blokajlar düşüldükten sonra üye işyerine gönderilecek tutar.
iyziConversationRate(ItemTransactions)(convertedPayout)	Decimal	Bu kırılım için, iyzico işlem ücreti, komisyon tutarı ve blokajlar düşüldükten sonra üye işyerine gönderilecek tutar.
iyziConversationRateAmount(ItemTransactions)(convertedPayout)	Decimal	Bu kırılım için, iyzico işlem ücreti, komisyon tutarı ve blokajlar düşüldükten sonra üye işyerine gönderilecek tutar.
currency(ItemTransactions)(convertedPayout)	String	Ödemenin alındığı para birimi.

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.

Servise gönderilmesi gereken parametreler şunlardır:

POST https://api.iyzipay.com/payment/v2/3dsecure/auth

Request Body

Name	Type	Description
locale	String	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	İ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 sipariş numarasıdır.
paymentId*	String	3D dönüş bağlantı adresinizden alacağınız paymentid değeridir.
paidPrice*	String	İndirim vade farkı vs. hesaplanmış POS’tan geçen, tahsil edilen, nihai tutar.
basketId*	String	Üye işyeri tarafından gönderilen sepet id’si.
currency*	String	Ödemenin alındığı para birimi.

200: OK

3DS V2 Tamamlama Dönen Parametreler

Parametre İsmi	Veri Tipi	Açıklama
status	String	Yapılan isteğin sonucunu bildirir. İşlem başarılı ise success, hatalı ise failure döner.
errorCode	String	İşlem hatalıysa, bu hataya dair belirtilen koddur.
errorMessage	String	İşlem hatalıysa, bu hataya dair belirtilen mesajdır. Locale parametresine göre dil desteği sunar.
errorGroup	String	İşlem hatalıysa, bu hataya dair belirtilen gruptur.
locale	String	İstekte belirtilen locale değeri geri dönülür, varsayılan değeri tr’dir.
systemTime	Long	Dönen sonucun o anki unix timestamp değeridir.
conversationId	String	İstek esnasında gönderilmişse, sonuçta aynen geri iletilir.
paymentId	String	Ödemeye ait id, üye işyeri tarafından mutlaka saklanmalıdır. Ödemenin iptali ve iyzico ile iletişimde kullanılır.
price	Decimal	Ödeme sepet tutarı. Kırılım tutarlar toplamı sepet tutarına eşit olmalı.
paidPrice	Decimal	İndirim vade farkı vs. hesaplanmış POS’tan geçen, tahsil edilen, nihai tutar.
currency	String	Ödemenin alındığı para birimi.
installment	Integer	Ödemenin taksit bilgisi, tek çekim için 1 döner. Geçerli değerler: 1, 2, 3, 6, 9, 12.
paymentStatus	String	İşlemin sonucunu gösterir. Geçerli değerler SUCCESS, FAILURE, INIT_THREEDS, CALLBACK_THREEDS, BKM_POS_SELECTED, CALLBACK_PECCO
basketId	String	Üye işyeri tarafından gönderilen sepet id’si.
binNumber	String	Ödeme yapılan kartın ilk 6 hanesi.
cardAssociation	String	Eğer ödeme yapılan kart yerel bir kart ise, kartın ait olduğu kuruluş. Geçerli değerler: VISA, MASTER_CARD, AMERICAN_EXPRESS, TROY
cardFamily	String	Eğer ödeme yapılan kart yerel bir kart ise, kartın ait olduğu aile. Geçerli değerler: Bonus, Axess, World, Maximum, Paraf, CardFinans, Advantage
cardType	String	Eğer ödeme yapılan kart yerel bir kart ise, kartın ait olduğu tipi. Geçerli değerler: CREDIT_CARD, DEBIT_CARD, PREPAID_CARD
fraudStatus	Integer	Ödeme işleminin fraud filtrelerine göre durumu. Eğer ödemenin fraud risk skoru düşük ise ödemeye anında onay verilir, bu durumda 1 değeri döner. Eğer fraud risk skoru yüksek ise ödeme işlemi reddedilir ve -1 döner. Eğer ödeme işlemi daha sonradan incelenip karar verilecekse 0 döner. Geçerli değerler: 0, -1 ve 1. Üye işyeri sadece 1 olan işlemlerde ürünü kargoya vermelidir, 0 olan işlemler için bilgilendirme beklemelidir.
iyziCommissionFee	Decimal	Ödemeye ait iyzico işlem ücreti.
iyziCommissionRateAmount	Decimal	Ödemeye ait iyzico işlem komisyon tutarı.
merchantCommissionRate	Decimal	Ü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.
merchantCommissionRateAmount	Decimal	Ü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.
paymentTransactionId (ItemTransactions)	String	Ödeme kırılımına ait id, üye işyeri tarafından mutlaka saklanmalıdır. Ödeme kırılımının iadesi, onayı, onay geri çekmesi ve iyzico ile iletişimde kullanılır. Tercihen itemId ile ilişkili bir şekilde tutulmalıdır.
itemId(ItemTransactions)	String	Üye işyeri tarafından iletilen, sepetteki ürüne ait id.
price(ItemTransactions)	Decimal	Üye işyeri tarafındaki sepetteki ürüne ait tutar.
paidPrice(ItemTransactions)	Decimal	Tahsilat tutarının kırılım bazındaki dağılımı. Üye işyeri tarafından mutlaka saklanmalıdır.
transactionStatus (ItemTransactions)	Integer	Ödeme kırılımının durumu. Ödeme fraud kontrolünde ise 0 değeri döner, bu durumda fraudStatus değeri de 0’dır. Ödeme, fraud kontrolünden sonra reddedilirse -1 döner. Pazaryeri modelinde ürüne onay verilene dek bu değer 1 olarak döner. Pazaryeri modelinde ürüne onay verilmişse bu değer 2 olur. Geçerli değerler: 0, -1, 1, 2.
blockageRate(ItemTransactions)	Decimal	Kırılım bazında üye işyeri blokaj oranı. iyzico – üye işyeri anlaşmasına göre, üye işyerine işlem bazında blokaj uygulayabilir. Bu blokaj üye işyeri fraud riskini önlemek içindir, blokaj süresi boyunca para iyzico’da tutulur, bu süre sonrasında üye işyerine gönderilir.
blockageRateAmountMerchant(ItemTransactions)	Decimal	Kırılım bazında üye işyeri blokaj tutarının, üye işyerine yansıyan rakamı. Blokaj tutarı mümkün olduğunca üye işyerine yansıtılır. Eğer blokaj tutarı, üye işyeri tutarından daha büyükse bu durumda alt üye işyerine de yansıtılır.
blockageResolvedDate(ItemTransactions)	String	İşlem bazında blokaj çözülme tarihi. yyyy-MM-dd HH:mm:ss formatındadır, örneğin 2015-10-19 14:36:52.
iyziCommissionFee(ItemTransactions)	Decimal	iyzico işlem ücretinin kırılım bazında dağılmış tutarı.
iyziCommissionRateAmount(ItemTransactions)	Decimal	iyzico işlem komisyon tutarının kırılım bazında dağılmış tutarı.
merchantCommissionRate(ItemTransactions)	Decimal	Üye işyerinin uyguladığı vade/komisyon oranının kırılım bazında dağılmış oranı.
merchantCommissionRateAmount(ItemTransactions)	Decimal	Üye işyerinin uyguladığı vade/komisyon tutarıın, kırılım bazında dağılmış tutarı.
merchantPayoutAmount(ItemTransactions)	Decimal	Bu kırılım için, iyzico işlem ücreti, komisyon tutarı ve blokajlar düşüldükten sonra üye işyerine gönderilecek tutar.
paidPrice(ItemTransactions)(convertedPayout)	Decimal	Tahsilat tutarının kırılım bazındaki dağılımı. Üye işyeri tarafından mutlaka saklanmalıdır.
iyziCommissionFee(ItemTransactions)(convertedPayout)	Decimal	iyzico işlem ücretinin kırılım bazında dağılmış tutarı.
iyziCommissionRateAmount(ItemTransactions)(convertedPayout)	Decimal	iyzico işlem komisyon tutarının kırılım bazında dağılmış tutarı.
blockageRateAmountMerchant(ItemTransactions)(convertedPayout)	Decimal	Kırılım bazında üye işyeri blokaj tutarının, üye işyerine yansıyan rakamı. Blokaj tutarı mümkün olduğunca üye işyerine yansıtılır. Eğer blokaj tutarı, üye işyeri tutarından daha büyükse bu durumda alt üye işyerine de yansıtılır.
merchantPayoutAmount(ItemTransactions)(convertedPayout)	Decimal	Bu kırılım için, iyzico işlem ücreti, komisyon tutarı ve blokajlar düşüldükten sonra üye işyerine gönderilecek tutar.
iyziConversationRate(ItemTransactions)(convertedPayout)	Decimal	Bu kırılım için, iyzico işlem ücreti, komisyon tutarı ve blokajlar düşüldükten sonra üye işyerine gönderilecek tutar.
iyziConversationRateAmount(ItemTransactions)(convertedPayout)	Decimal	Bu kırılım için, iyzico işlem ücreti, komisyon tutarı ve blokajlar düşüldükten sonra üye işyerine gönderilecek tutar.
currency(ItemTransactions)(convertedPayout)	String	Ödemenin alındığı para birimi.

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.