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

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

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

Finalizes a 3DS v2 payment after successful 3D Secure 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 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

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 8 days ago