Adımlar
Genel Özet
Örnek Uygulama
Temel NON-3DS uygulaması, kısaca birbirini takip eden iki POST isteğinden oluşur.
Önerilen entegrasyon aşağıdaki sırayla izlenir;
1. BIN Check
İster 3DS ister NON-3DS ödeme yöntemi olsun, alışverişte kullanılacak kartın özelliğinin önceden belirlenmesi tavsiye edilir. BIN detay hizmetleri sayesinde kart türü, kart şeması, kart ile ilgili taksit bilgileri ve 3DS özelliklerine ilişkin daha ayrıntılı bilgiler alınır.
Taksit Bilgisini Almaya Yönelik Örnek İstek;
Copy {
"price" : "100.0" ,
"binNumber" : "535805"
} Taksit Bilgisini Almaya Yönelik Örnek Yanıt;
Copy {
"status" : "success" ,
"locale" : "tr" ,
"systemTime" : 1685905139724 ,
"installmentDetails" : [
{
"binNumber" : "535805" ,
"price" : 100.0 ,
"cardType" : "DEBIT_CARD" ,
"cardAssociation" : "MASTER_CARD" ,
"cardFamilyName" : "iyzico DC" ,
"force3ds" : 0 ,
"bankCode" : 864 ,
"bankName" : "iyzico" ,
"forceCvc" : 0 ,
"commercial" : 0 ,
"dccEnabled" : 0 ,
"installmentPrices" : [
{
"installmentPrice" : 100.0 ,
"totalPrice" : 100.0 ,
"installmentNumber" : 1
}
]
}
]
}
2. Init 3DS
3DS ödeme yolculuğu, 3DS POST isteğinin başlatılmasıyla başlar.
Örnek 3DS Başlatma İsteği;
Copy {
"locale" : "en" ,
"price" : "3.2" ,
"paidPrice" : "3.2" ,
"installment" : 1 ,
"paymentChannel" : "WEB" ,
"basketId" : "B67832" ,
"paymentGroup" : "PRODUCT" ,
"paymentCard" : {
"cardHolderName" : "Dev iyzico" ,
"cardNumber" : "5526080000000006" ,
"expireYear" : "2023" ,
"expireMonth" : "11" ,
"cvc" : "200"
} ,
"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" : "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1" ,
"city" : "Istanbul" ,
"country" : "Turkey" ,
"zipCode" : "34732" ,
"ip" : "85.34.78.112"
} ,
"conversationId" : "deviyzico" ,
"shippingAddress" : {
"address" : "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1" ,
"zipCode" : "34742" ,
"contactName" : "Jane Doe" ,
"city" : "Istanbul" ,
"country" : "Turkey"
} ,
"billingAddress" : {
"address" : "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1" ,
"zipCode" : "34742" ,
"contactName" : "Jane Doe" ,
"city" : "Istanbul" ,
"country" : "Turkey"
} ,
"basketItems" : [
{
"id" : "BI101" ,
"price" : "1.1" ,
"name" : "Binocular" ,
"category1" : "Collectibles" ,
"category2" : "Accessories" ,
"itemType" : "PHYSICAL"
} ,
{
"id" : "BI1012" ,
"price" : "2.1" ,
"name" : "Binocular" ,
"category1" : "Collectibles" ,
"category2" : "Accessories" ,
"itemType" : "PHYSICAL"
}
] ,
"currency" : "TRY" ,
"callbackUrl" : "https://deviyzico.com/"
}n Karşılığında diğer parçalarla birlikte " threeDSHtmlContent" anahtar/değerinin alınması beklenir.
Örnek 3DS Başlatma Yanıtı;
Copy {
"status" : "success" ,
"locale" : "en" ,
"systemTime" : 1685539494559 ,
"conversationId" : "deviyzico" ,
"threeDSHtmlContent": "PCFkb2N0eXBlIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KPGhlYWQ+CiAgICA8dGl0bGU+aXl6aWNvIE1vY2sgM0QtU2VjdXJlIFByb2Nlc3NpbmcgUGFnZTwvdGl0bGU+CjwvaGVhZD4KPGJvZHk+Cjxmb3JtIGlkPSJpeXppY28tM2RzLWZvcm0iIGFjdGlvbj0iaHR0cHM6Ly9zYW5kYm94LWFwaS5peXppcGF5LmNvbS9wYXltZW50L21vY2svaW5pdDNkcyIgbWV0aG9kPSJwb3N0Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9Im9yZGVySWQiIHZhbHVlPSJtb2NrNDYtNjg3NjU1ODAwODI2MjM5NWl5emlvcmQiPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iYmluIiB2YWx1ZT0iNTUyNjA4Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9InN1Y2Nlc3NVcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvaXl6aXBvcy9jYWxsYmFjazNkcy9zdWNjZXNzLzI3Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9ImZhaWx1cmVVcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvaXl6aXBvcy9jYWxsYmFjazNkcy9mYWlsdXJlLzI3Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9ImNvbmZpcm1hdGlvblVybCIgdmFsdWU9Imh0dHBzOi8vc2FuZGJveC1hcGkuaXl6aXBheS5jb20vcGF5bWVudC9tb2NrL2NvbmZpcm0zZHMiPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iUGFSZXEiIHZhbHVlPSJjYWIxNjA0YS02MWJiLTQ0NGQtOGExNS1kZDZmMzhjZGRiNjMiPgo8L2Zvcm0+CjxzY3JpcHQgdHlwZT0idGV4dC9qYXZhc2NyaXB0Ij4KICAgIGRvY3VtZW50LmdldEVsZW1lbnRCeUlkKCJpeXppY28tM2RzLWZvcm0iKS5zdWJtaXQoKTsKPC9zY3JpcHQ+CjwvYm9keT4KPC9odG1sPg=="
}
3. "threeDSHtmlContent" Kodu Çözme
"threeDSHtmlContent", şifrelenmiş 3DS formunun kendisini temsil eder. 3DS başlangıcının yanıtından kodlanmış " threeDSHtmlContent" parametresini tarayıcıda render ettiğimizde tüketicinin karşısına 3DS ekranı çıkacaktır.
Kodu Çözülmüş "thirdDSHtmlContent" Sandbox Örneği;
Copy "threeDSHtmlContent": "PCFkb2N0eXBlIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KPGhlYWQ+CiAgICA8dGl0bGU+aXl6aWNvIE1vY2sgM0QtU2VjdXJlIFByb2Nlc3NpbmcgUGFnZTwvdGl0bGU+CjwvaGVhZD4KPGJvZHk+Cjxmb3JtIGlkPSJpeXppY28tM2RzLWZvcm0iIGFjdGlvbj0iaHR0cHM6Ly9zYW5kYm94LWFwaS5peXppcGF5LmNvbS9wYXltZW50L21vY2svaW5pdDNkcyIgbWV0aG9kPSJwb3N0Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9Im9yZGVySWQiIHZhbHVlPSJtb2NrNDYtNjg3NjU1ODAwODI2MjM5NWl5emlvcmQiPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iYmluIiB2YWx1ZT0iNTUyNjA4Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9InN1Y2Nlc3NVcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvaXl6aXBvcy9jYWxsYmFjazNkcy9zdWNjZXNzLzI3Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9ImZhaWx1cmVVcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvaXl6aXBvcy9jYWxsYmFjazNkcy9mYWlsdXJlLzI3Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9ImNvbmZpcm1hdGlvblVybCIgdmFsdWU9Imh0dHBzOi8vc2FuZGJveC1hcGkuaXl6aXBheS5jb20vcGF5bWVudC9tb2NrL2NvbmZpcm0zZHMiPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iUGFSZXEiIHZhbHVlPSJjYWIxNjA0YS02MWJiLTQ0NGQtOGExNS1kZDZmMzhjZGRiNjMiPgo8L2Zvcm0+CjxzY3JpcHQgdHlwZT0idGV4dC9qYXZhc2NyaXB0Ij4KICAgIGRvY3VtZW50LmdldEVsZW1lbnRCeUlkKCJpeXppY28tM2RzLWZvcm0iKS5zdWJtaXQoKTsKPC9zY3JpcHQ+CjwvYm9keT4KPC9odG1sPg==" Kodlanmış "thirdDSHtmlContent" Sandbox Örneği;
Copy <!doctype html>
<html lang= "en" >
<head>
<title>iyzico Mock 3 D-Secure Processing Page</title>
</head>
<body>
<form id= "iyzico-3ds-form" action= "https://sandbox-api.iyzipay.com/payment/mock/init3ds" method= "post" >
<input type= "hidden" name= "orderId" value= "mock46-6876558008262395iyziord" >
<input type= "hidden" name= "bin" value= "552608" >
<input type= "hidden" name= "successUrl" value= "https://sandbox-api.iyzipay.com/payment/iyzipos/callback3ds/success/27" >
<input type= "hidden" name= "failureUrl" value= "https://sandbox-api.iyzipay.com/payment/iyzipos/callback3ds/failure/27" >
<input type= "hidden" name= "confirmationUrl" value= "https://sandbox-api.iyzipay.com/payment/mock/confirm3ds" >
<input type= "hidden" name= "PaReq" value= "cab1604a-61bb-444d-8a15-dd6f38cddb63" >
<input type= "hidden" name= "termUrl" value= "cab1604a-61bb-444d-8a15-dd6f38cddb63" >
<input type= "hidden" name= "md" value= "cab1604a-61bb-444d-8a15-dd6f38cddb63" >
</form>
<script type= "text/javascript" >
document.getElementById( "iyzico-3ds-form" ).submit();
</script>
</body>
</html> Tarayıcıdaki kodu çözülmüş threeDSHtmlContent arayüzünün bir örneği;
4. Yönlendirme
Yeniden yönlendirme aşaması, 3DS Başlatma ve 3DS Tamamlama adımlarını genel olarak birbirine bağlar.
Kart sahibi OTP (Tek Kullanımlık Şifre) onayının ardından iyzico, sayfayı otomatik olarak "callbackUrl" parametresinde belirtilen adrese yönlendirecektir. Yönlendirme POST'u şunları içerir;
Parametre ismi
Tip
Açıklama
Yapılan isteğin sonucunu bildirir. İşlem başarılı ise success, hatalı ise failure döner.
İşlem success yani başarılı ise, iyzico tarafından o ödemeye verilen değerdir. 3D bitirme sorgusunda kullanılacaktır.
İşlem success yani başarılı ise, iyzico tarafından o ödemeye verilen değerdir. Bütün durumlarda dolu gelmeyebilir. Eğer dolu gelirse bu parametrenin de 3D bitirme sorgusunda gönderilmesi gerekir.
Başlatma sorgusunda gönderilen conversationId değeridir.
Bilgilendirme amaçlı dönen mdStatus değeridir. Başarılı durumlar için 1 başarısız durumlar için ise 0,2,3,4,5,6,7,8 olarak dönebilir.
mdStatus
"mdStatus", işlem sonucunu 3DS üçgeninde yorumlar.
Başarılı 3DS operasyonları "callbackUrl" üzerinde "mdStatus":"1" ile sonuçlanırken, başarısızlık senaryolarında aşağıdaki listeden biri olabilir;
3-D Secure imzası geçersiz veya doğrulama.
mdStatus = 0 ile aynıdır. QNB Finansbank'a özel dönüştür.
Kart sahibi veya bankası sisteme kayıtlı değil.
Kartın bankası sisteme kayıtlı değil.
Doğrulama denemesi, kart sahibi sisteme daha sonra kayıt olmayı seçmiş.
5. 3DS Tamamlama
Yukarıdaki tüm adımları tamamladıktan sonra, artık ödeme işlemini 3DS Tamamlama talebi ile resmileştirme zamanı.
Örnek 3DS Tamamlama İsteği;
Copy {
"paymentId" : "123456789"
} Örnek 3DS Tamamlama Yanıtı;
Copy {
"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"
} NOT : mdStatus parametresi sadece 3DS işlemlerinde görünecektir.
6. Webhook
Webhook’lar 3DS akışımızın son konusudur.
Gerçek zamanlı ödeme bildirimlerinin alınması, genel olarak 3DS deneyiminden yararlanırken bildirimlerin güvenilir kaynaklardan gelmesini sağlar ve hassas verilere olası müdahaleleri veya yetkisiz erişimi önler.
Her ödeme olayı Webhook’ları tetikler;
Sunucunuz 200 yanıtını alana kadar.
Örnek Webhook 3DS Yetkilendirmesi
Parametere
Type
Description
Unix timestamp value of first notification.
Shows the request type. Values: API_AUTH, THREE_DS_AUTH, BKM_AUTH
A unique reference code for the notification
Unique iyzico reference code of related payment
Merchant's reference id for the related payment
Payment status. Values: SUCCESS, FAILURE
Olumlu senaryo status değişkeninin success dönmesiyle gerçekleşir.
Doğrulama
Ödeme işlemlerinin başarılı bir şekilde sonuçlandırılmasında belirli değişkenlerin korelasyonu önemli rol oynar;
Diğer Eşleştirme parametreleri opsiyoneldir.
3DS Tamamlama yanıtı ve Webhook bildiriminin birbirini doğrulaması hayati önem taşımaktadır.
3DS Tamamlama yanıtında bulunan paymentId değişkeni Webhook’tan gelen paymentId değişkeniyle aynı olmalıdır.
Her iki istekten gelen status değişkeni success olmalıdır.
price parametresindeki miktar aynı olmalıdır.
Ve son olarak, Eşleştirme parametreleri de eşit olmalıdır.
Eğer eşitse, tebrikler! 3DS entegrasyonunu bitirdiniz.
İşlem detaylarına panelinizden ulaşabilirsiniz.
Hangi Ürünlerle Birlikte Kullanılabilir?
Avantajlar
1.X.X veya 2.X.X'i kapsayan tek 3DS yöntemi
Diğer iyzico API'leri ile kullanım kolaylığı
.svg?alt=media&token=17ec6f8f-ac20-4c93-8c47-630298706a48)
