3DS Başlatma

3DS Başlatma API’si müşterinin kart ödemelerinin 3DS ile işlenmesinden sorumludur.

NON-3DS entegrasyonunda olduğu gibi;

• TROY, MASTERCARD, VISA ve AMEX markalı kartlarla yapılan işlemleri destekler.

• BONUS, WORLD, MAXIMUM, AXESS, CARDFINANS, PARAF, ADVANTAGE gibi taksit programlarına katılmış olan kartlara 2, 3, 6, 9 ve 12 taksit seçenekleri sunulmaktadır.

• Panelde başarılı işlemler yeşil renkte, başarısız işlemler ise kırmızı renkte görüntülenir.

• Üye iş yeri, conversationId ve basketId parametrelerini kendi tarafında sipariş numarası olarak kullanabilir.

Bu özellikleri birleştirerek müşterilerinize, işlemlerinin başarısı veya başarısızlığı hakkında gerçek zamanlı geri bildirim sağlayarak kusursuz bir ödeme deneyimi sağlayabilirsiniz.

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

statusstring · enumOptional

Yapılan isteğin sonucunu bildirir.

Example: successPossible values:

localestringOptional

Yanıt dili (tr/en).

Example: tr

systemTimeintegerOptional

İşlem zamanı (epoch ms).

Example: 1755197726218

conversationIdstringOptional

İstek ile eşleşen ID.

Example: conversationId

threeDSHtmlContentstringOptional

3DS doğrulama ekranının Base64 kodlu HTML içeriği.

Example: PCFkb2N0eXBlIGh0bWw+...

paymentIdstringOptional

iyzico tarafından dönen uniq paymentId bilgisi.

Example: 25149157

signaturestringOptional

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

Example: c8964a1878f9dae20741209dea6749d16bac4a8760775ae69b0b2420d9dc024b

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

Örnek Kodlar

PHP

Java

.NET

Node.Js

Python

Son olarak aşağıdaki başlıkları analiz ederek, ödeme sorgusunun sonucunu etkili bir şekilde yönetebilir ve yanıtlayabilirsiniz, böylece müşterileriniz için sorunsuz ve güvenilir bir ödeme süreci sağlayabilirsiniz.

• status parametresi işlemin durumu hakkında bilgi sağlar. success, işlemin başarıyla tamamlandığını ve ödemenin işlendiğini gösterir. failure, işlemin başarısız olduğunu belirtir ve başarısızlığın nedenine ilişkin bir hata mesajı verilir.

• Bu hizmet için paymentStatus parametresi boştur.

• paymentId ve paymentTransactionId değerleri, ileride referans noktası olarak kullanılabileceği için saklanmalıdır.

• Başarısız bir işlem durumunda (failure durumu), errorCode, errorMessage ve errorGroup parametreleri, hatayla ilgili ayrıntıları sağlayarak ilgili değerlerle birlikte döndürülür.