Init 3DS

Init 3DS API is responsible for processing the customer's card payments with 3DS.

As like Its ancestor NON-3DS;

• It supports transactions made with TROY, MASTERCARD, VISA, and AMEX branded cards.

• For cards participating in installment programs such as BONUS, WORLD, MAXIMUM, AXESS, CARDFINANS, PARAF, and ADVANTAGE, the service allows options for 2, 3, 6, 9, and 12 installments.

• Successful transactions are displayed in green, while failed transactions are displayed in red on the panel.

• The merchant can utilize the conversationId and basketId parameters as order numbers on their side.

By incorporating these features, you can provide a seamless payment experience for your customers, with real-time feedback on the success or failure of their transactions.

Initialize 3DS Payment

post

Starts a 3D Secure session and returns an htmlContent value for 3DS authentication.

Header parameters

AuthorizationstringRequired

Authorization header; a signed Base64-encoded hash that starts with IYZWSv2.

Example: IYZWSv2 aXBzaWduYXR1cmU...

Content-TypestringRequired

Content-Type value.

Example: application/json

Body

application/json

localestring · enumOptional

Language code. Default; tr

Example: enPossible values:

conversationIdstringOptional

Unique ID for request/response correlation.

Example: conversationId

pricedecimalRequired

Basket total amount.

Example: 1

paidPricedecimalRequired

Final amount to be charged to the customer.

Example: 1

currencystring · enumOptional

Currency. Default; TRY.

Example: TRYPossible values:

installmentinteger · enumOptional

Installment count (if omitted, a single installment is used).

Example: 1Possible values:

paymentChannelstring · enumOptional

Payment channel.

Example: WEBPossible values:

basketIdstringOptional

Basket ID.

Example: basketId

paymentGroupstring · enumOptional

Payment group. Default; PRODUCT.

Example: PRODUCTPossible values:

callbackUrlstringRequired

Redirect URL after 3DS flow completes.

Example: https://callbackurl.com

Responses

200

Successful response (3DS initialized)

application/json

statusstring · enumOptional

Result of the request.

Example: successPossible values:

localestringOptional

Response language (tr/en).

Example: en

systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755197726218

conversationIdstringOptional

ID matching the request.

Example: conversationId

threeDSHtmlContentstringOptional

Base64-encoded HTML content of the 3DS verification screen.

Example: PCFkb2N0eXBlIGh0bWw+...

paymentIdstringOptional

Unique paymentId returned by iyzico.

Example: 25149157

signaturestringOptional

Signature value that can be used for verification.

Example: c8964a1878f9dae20741209dea6749d16bac4a8760775ae69b0b2420d9dc024b

400

Invalid request / validation error

application/json

post

/payment/3dsecure/initialize

HTTP

POST https://api.iyzipay.com/payment/3dsecure/initialize
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "en",
  "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" }
  ]
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1755197726218,
  "conversationId": "conversationId",
  "threeDSHtmlContent": "PCFkb2N0eXBlIGh0bWw+...",
  "paymentId": "25149157",
  "signature": "c8964a1878f9dae20741209dea6749d16bac4a8760775ae69b0b2420d9dc024b"
}

Sample Codes

PHP

Java

.Net

Node.Js

Python

Postman

Lastly analyzing following headlines, you can effectively handle and respond to the outcome of the payment inquiry, ensuring a smooth and reliable payment process for your customers.

• The status parameter provides information about the status of the transaction. success indicates that the transaction has been successfully completed and the payment has been processed. failure indicates that the transaction has failed, and an error message related to the failure reason is provided.

• The paymentStatus parameter is null for this service.

• The paymentId and paymentTransactionId values should be stored for future reference and tracking.

• In the event of a failed transaction (failure status), the errorCode, errorMessage, and errorGroup parameters will be returned with corresponding values, providing details about the error.