3DS Entegrasyonu

Adımlar

1. BIN Sorgulama

2. 3DS Başlatma

3. "threeDSHtmlContent" Decode

4. Yönlendirme

5. 3DS Tamamlama

6. Webhook

Genel Özet

• BIN Sorgulama; API'nin taksit seçenekleri ve kart ayrıntıları hakkında bilgi döndürdüğü, kartı veren kuruluşun ayrıntılarını tanımladığı bölüm.

• 3DS Başlatma; iki adımlı 3DS işlemlerini yönetmeye ilişkin ilk POST isteği

• " threeDSHtmlContent"; son kullanıcınızın 3DS sayfa OTP doğrulamasını doğrulamasını beklediği base64 şifreli HTML sayfası.

• Yönlendirme; Tüketicilerin ödemelerini takip eden iyzico, verilen callbackUrl'si ile ilişkilendirilen IPN'i (Anında Ödeme Bildirimi) tetikler.

• 3DS Tamamlama; Acquirer ve Issuer arasındaki işlemi resmileştirmek için gerçekleştirilen adım.

• Webhook; İlgili ödemenin gerçek zamanlı bildirimi.

Örnek Uygulama

Temel NON-3DS uygulaması, kısaca birbirini takip eden iki POST isteğinden oluşur.

• 3DS Başlatma

• 3DS Tamamlama

Ö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;

{
"price":"100.0",
"binNumber":"535805"
}

Taksit Bilgisini Almaya Yönelik Örnek Yanıt;

{
    "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;

{
    "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": "[e-mail]",
        "gsmNumber": "[phone]",
        "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ı;

{
    "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;

"threeDSHtmlContent": "PCFkb2N0eXBlIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KPGhlYWQ+CiAgICA8dGl0bGU+aXl6aWNvIE1vY2sgM0QtU2VjdXJlIFByb2Nlc3NpbmcgUGFnZTwvdGl0bGU+CjwvaGVhZD4KPGJvZHk+Cjxmb3JtIGlkPSJpeXppY28tM2RzLWZvcm0iIGFjdGlvbj0iaHR0cHM6Ly9zYW5kYm94LWFwaS5peXppcGF5LmNvbS9wYXltZW50L21vY2svaW5pdDNkcyIgbWV0aG9kPSJwb3N0Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9Im9yZGVySWQiIHZhbHVlPSJtb2NrNDYtNjg3NjU1ODAwODI2MjM5NWl5emlvcmQiPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iYmluIiB2YWx1ZT0iNTUyNjA4Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9InN1Y2Nlc3NVcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvaXl6aXBvcy9jYWxsYmFjazNkcy9zdWNjZXNzLzI3Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9ImZhaWx1cmVVcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvaXl6aXBvcy9jYWxsYmFjazNkcy9mYWlsdXJlLzI3Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9ImNvbmZpcm1hdGlvblVybCIgdmFsdWU9Imh0dHBzOi8vc2FuZGJveC1hcGkuaXl6aXBheS5jb20vcGF5bWVudC9tb2NrL2NvbmZpcm0zZHMiPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iUGFSZXEiIHZhbHVlPSJjYWIxNjA0YS02MWJiLTQ0NGQtOGExNS1kZDZmMzhjZGRiNjMiPgo8L2Zvcm0+CjxzY3JpcHQgdHlwZT0idGV4dC9qYXZhc2NyaXB0Ij4KICAgIGRvY3VtZW50LmdldEVsZW1lbnRCeUlkKCJpeXppY28tM2RzLWZvcm0iKS5zdWJtaXQoKTsKPC9zY3JpcHQ+CjwvYm9keT4KPC9odG1sPg=="

Kodlanmış "thirdDSHtmlContent" Sandbox Örneği;

<!doctype html>
<html lang="en">
<head>
    <title>iyzico Mock 3D-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
status	String	Yapılan isteğin sonucunu bildirir. İşlem başarılı ise success, hatalı ise failure döner.
paymentId	String	İşlem success yani başarılı ise, iyzico tarafından o ödemeye verilen değerdir. 3D bitirme sorgusunda kullanılacaktır.
conversationData	String	İş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.
conversationId	Long	Başlatma sorgusunda gönderilen conversationId değeridir.
mdStatus	String	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;

mdStatus	Açıklama
mdStatus = 0	3-D Secure imzası geçersiz veya doğrulama.
mdStatus = -1	mdStatus = 0 ile aynıdır. QNB Finansbank'a özel dönüştür.
mdStatus = 2	Kart sahibi veya bankası sisteme kayıtlı değil.
mdStatus = 3	Kartın bankası sisteme kayıtlı değil.
mdStatus = 4	Doğrulama denemesi, kart sahibi sisteme daha sonra kayıt olmayı seçmiş.
mdStatus = 5	Doğrulama yapılamıyor.
mdStatus = 6	3-D Secure hatası.
mdStatus = 7	Sistem hatası.
mdStatus = 8	Bilinmeyen kart no.

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;

{
  "paymentId": "123456789"
}

Örnek 3DS Tamamlama Yanıtı;

{
    "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;

• Her 15 saniyede bir

• Sunucunuz 200 yanıtını alana kadar.

• Her 10 dakikada bir

• Maksimum 3 kere

Örnek Webhook 3DS Yetkilendirmesi

Parametere	Type	Description
iyziEventTime	long	Unix timestamp value of first notification.
iyziEventType	string	Shows the request type. Values: API_AUTH, THREE_DS_AUTH, BKM_AUTH
iyziReferenceCode	string	A unique reference code for the notification
paymentId	long	Unique iyzico reference code of related payment
paymentConversationId	string	Merchant's reference id for the related payment
status	string	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;

• paymentId

• status

• price

• 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?

Online Ödeme

Pazaryeri

Abonelik

iyzilink

Ödeme Formu (CheckoutForm)

iyzico ile Öde (PWI)

Avantajlar

• Daha hızlı entegrasyon

• 1.X.X veya 2.X.X'i kapsayan tek 3DS yöntemi

• Diğer iyzico API'leri ile kullanım kolaylığı