API - 3DS

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

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

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": "+905350000000",
    "registrationDate": "2013-04-21 15:12:09",
    "lastLoginDate": "2015-10-05 12:43:35",
    "registrationAddress": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "city": "İstanbul",
    "country": "Turkey",
    "zipCode": "34732",
    "ip": "85.34.78.112"
  },
  "shippingAddress": {
    "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "zipCode": "34742",
    "contactName": "Jane Doe",
    "city": "Istanbul",
    "country": "Turkey"
  },
  "billingAddress": {
    "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İ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"
}

Create 3DS Payment

post

Finalizes the payment after successful 3D 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

localestring · enumOptional

Language code. Default; tr

Example: enPossible values:

paymentIdstringRequired

Payment ID returned by the initialize call.

Example: 25149157

conversationIdstringOptional

Unique ID for request/response correlation.

Example: conversationId

conversationDatastringOptional

Data posted by the 3DS result. If present, it must be sent.

Responses

200

Successful response (payment completed)

application/json

400

Invalid request / validation error

application/json

post

/payment/3dsecure/auth

HTTP

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

{
  "locale": "tr",
  "paymentId": "25149157",
  "conversationId": "conversationId",
  "conversationData": ""
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1755198001941,
  "conversationId": "conversationId",
  "price": 1,
  "paidPrice": 1,
  "installment": 1,
  "paymentId": "25149157",
  "fraudStatus": 1,
  "merchantCommissionRate": 0,
  "merchantCommissionRateAmount": 0,
  "iyziCommissionRateAmount": 0.0349,
  "iyziCommissionFee": 0.25,
  "cardType": "CREDIT_CARD",
  "cardAssociation": "MASTER_CARD",
  "cardFamily": "Paraf",
  "binNumber": "552879",
  "lastFourDigits": "0008",
  "basketId": "basketId",
  "currency": "TRY",
  "itemTransactions": [
    {
      "itemId": "BI101",
      "paymentTransactionId": "27138714",
      "transactionStatus": 2,
      "price": 0.4,
      "paidPrice": 0.4,
      "merchantCommissionRate": 0,
      "merchantCommissionRateAmount": 0,
      "iyziCommissionRateAmount": 0.01396,
      "iyziCommissionFee": 0.1,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-08-22 00:00:00",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 0.28604,
      "convertedPayout": {
        "paidPrice": 0.4,
        "iyziCommissionRateAmount": 0.01396,
        "iyziCommissionFee": 0.1,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 0.28604,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    },
    {
      "itemId": "BI102",
      "paymentTransactionId": "27138715",
      "transactionStatus": 2,
      "price": 0.3,
      "paidPrice": 0.3,
      "merchantCommissionRate": 0,
      "merchantCommissionRateAmount": 0,
      "iyziCommissionRateAmount": 0.01047,
      "iyziCommissionFee": 0.075,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-08-22 00:00:00",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 0.21453,
      "convertedPayout": {
        "paidPrice": 0.3,
        "iyziCommissionRateAmount": 0.01047,
        "iyziCommissionFee": 0.075,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 0.21453,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    },
    {
      "itemId": "BI103",
      "paymentTransactionId": "27138716",
      "transactionStatus": 2,
      "price": 0.3,
      "paidPrice": 0.3,
      "merchantCommissionRate": 0,
      "merchantCommissionRateAmount": 0,
      "iyziCommissionRateAmount": 0.01047,
      "iyziCommissionFee": 0.075,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-08-22 00:00:00",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 0.21453,
      "convertedPayout": {
        "paidPrice": 0.3,
        "iyziCommissionRateAmount": 0.01047,
        "iyziCommissionFee": 0.075,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 0.21453,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    }
  ],
  "authCode": "214525",
  "phase": "AUTH",
  "mdStatus": 1,
  "hostReference": "mock00001iyzihostrfn",
  "signature": "5f510cd92b4b9c50a39b617cda228f4159f290860a4c20a965c55b119c9e9052"
}

Create 3DS v2 Payment

post

After the verification step, both the v1 and the new-generation v2 endpoints can be used to finalize the payment. However, to align with more advanced and secure technologies, the use of the v2 endpoint is recommended.

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

localestring · enumOptional

Language code. Default; tr

Example: enPossible values:

paymentIdstringRequired

Payment ID returned after 3DS initialization.

Example: 25146302

conversationIdstringOptional

Unique ID for request/response correlation.

Example: conversationId

paidPricedecimalRequired

Collected amount to be used in 3DS v2 completion. Must match the paidPrice sent in INIT 3DS.

Example: 1

basketIdstringRequired

Basket ID (must match INIT 3DS basketId).

Example: basketId

currencystring · enumRequired

Currency. Default; TRY (must match the value sent in INIT 3DS).

Example: TRYPossible values:

Responses

200

Successful response (payment completed)

application/json

400

Invalid request / validation error

application/json

post

/payment/v2/3dsecure/auth

HTTP

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

{
  "locale": "tr",
  "paymentId": "25146302",
  "conversationId": "conversationId",
  "paidPrice": 1.0,
  "basketId": "basketId",
  "currency": "TRY"
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1755203584577,
  "conversationId": "conversationId",
  "price": 1,
  "paidPrice": 1,
  "installment": 1,
  "paymentId": "25149538",
  "fraudStatus": 1,
  "merchantCommissionRate": 0,
  "merchantCommissionRateAmount": 0,
  "iyziCommissionRateAmount": 0.0349,
  "iyziCommissionFee": 0.25,
  "cardType": "CREDIT_CARD",
  "cardAssociation": "MASTER_CARD",
  "cardFamily": "Paraf",
  "binNumber": "552879",
  "lastFourDigits": "0008",
  "basketId": "basketId",
  "currency": "TRY",
  "paymentChannel": "WEB",
  "itemTransactions": [
    {
      "itemId": "BI101",
      "paymentTransactionId": "27139066",
      "transactionStatus": 2,
      "price": 0.4,
      "paidPrice": 0.4,
      "merchantCommissionRate": 0,
      "merchantCommissionRateAmount": 0,
      "iyziCommissionRateAmount": 0.01396,
      "iyziCommissionFee": 0.1,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-08-22 00:00:00",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 0.28604,
      "convertedPayout": {
        "paidPrice": 0.4,
        "iyziCommissionRateAmount": 0.01396,
        "iyziCommissionFee": 0.1,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 0.28604,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    }
  ],
  "authCode": "847162",
  "phase": "AUTH",
  "mdStatus": 1,
  "hostReference": "mock00001iyzihostrfn",
  "signature": "f95c9246235c30cad41169bb1df7381b7ffe42bf1ea1226c2dd211e83dfe40f7"
}

PreviousAPI - NON3D NextPay with iyzico

Last updated 2 months ago