Ctrlk
GitHubFeedback Form
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Auth 3DS

To retrieve the details of a transaction registered in iyzico, you can use the payment inquiry service.

The parameters that need to be sent to the service are as follows:

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
statusstring · enumOptional

It reports the result of the transaction. If the response returns success, it means the payment has been completed successfully.

Example: successPossible values:
localestringOptional

Response language (tr/en).

Example: en
systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755198001941
conversationIdstringOptional

ID matching the request.

Example: conversationId
pricedecimalOptional

Basket total amount.

Example: 1
paidPricedecimalOptional

Total charged amount.

Example: 1
installmentintegerOptional

Installment count.

Example: 1
paymentIdstringOptional

Payment ID.

Example: 25149157
fraudStatusinteger · enumOptional

Payment status according to fraud filters.

  • 1: Approved
  • 0: Under review
  • -1: Declined
Example: 1Possible values:
merchantCommissionRatedecimalOptional

Merchant’s installment/commission rate (informational).

Example: 0
merchantCommissionRateAmountdecimalOptional

Merchant’s installment/commission amount (informational).

Example: 0
iyziCommissionRateAmountdecimalOptional

iyzico commission amount.

Example: 0.2094
iyziCommissionFeedecimalOptional

iyzico transaction fee.

Example: 0.25
cardTypestringOptional

Card type.

Example: CREDIT_CARD
cardAssociationstring · enumOptional

Card scheme/brand.

Example: MASTER_CARDPossible values:
cardFamilystringOptional

Card product/family.

Example: Axess
binNumberstringOptional

BIN (first 8 digits).

Example: 552608
lastFourDigitsstringOptional

Last 4 digits of the card.

Example: 0006
basketIdstringOptional

Basket ID.

Example: basketId
currencystringOptional

Currency of the payment.

Example: TRY
authCodestringOptional

Authorization code returned by the bank.

Example: 214525
phasestringOptional

Payment phase.

Example: AUTH
mdStatusinteger · enumOptional

3DS authentication result (1 means successful).

Example: 1Possible values:
hostReferencestringOptional

Host reference returned by the bank/acquirer.

Example: mock00001iyzihostrfn
signaturestringOptional

Signature value that can be used for verification.

Example: 5f510cd92b4b9c50a39b617cda228f4159f290860a4c20a965c55b119c9e9052
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"
}

Sample Codes

PHP

Java

.Net

Node.Js

Python

Postman

Auth 3DS v2 Request - Advanced Data Protection

At iyzico, following the recent HMACSHA256 update, we launched the payment/v2/3dsecure/auth endpoint alongside the existing payment/3dsecure/auth endpoint. This endpoint is used to finalize registered 3D payments and retrieve details of the corresponding transactions by including the final amount charged to the customer’s card, its conversationId and paymentId.

With this, more reliable validation techniques can be used to complete the respective payment. As mentioned on the Response Signature Validation, the variables listed in the request table, returned as a result of the payment request, play a crucial role in this process.

As shown on the Response Signature Validation, when a signature is generated for the encrypted payload on both sides and these signatures are equal, the respective payment is successfully completed.

The parameters that need to be sent to the service are as follows:

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
statusstring · enumOptional

It reports the result of the transaction. If the response returns success, it means the payment has been completed successfully.

Example: successPossible values:
localestring · enumOptional

Response language.

Example: enPossible values:
systemTimeintegerOptional

Timestamp (epoch ms).

Example: 1755203584577
conversationIdstringOptional

ID matching the request.

Example: conversationId
pricedecimalOptional

Basket total amount.

Example: 1
paidPricedecimalOptional

Total charged amount.

Example: 1
installmentintegerOptional

Installment count.

Example: 1
paymentIdstringOptional

Payment ID.

Example: 25149538
fraudStatusinteger · enumOptional

Payment status according to fraud filters.

  • 1: Approved
  • 0: Under review
  • -1: Declined
Example: 1Possible values:
merchantCommissionRatedecimalOptional

Merchant’s installment/commission rate (informational).

Example: 0
merchantCommissionRateAmountdecimalOptional

Merchant’s installment/commission amount (informational).

Example: 0
iyziCommissionRateAmountdecimalOptional

iyzico commission amount.

Example: 0.2094
iyziCommissionFeedecimalOptional

iyzico transaction fee.

Example: 0.25
cardTypestringOptional

Card type.

Example: CREDIT_CARD
cardAssociationstring · enumOptional

Card scheme/brand.

Example: MASTER_CARDPossible values:
cardFamilystringOptional

Card product/family.

Example: Axess
binNumberstringOptional

BIN (first 8 digits).

Example: 552608
lastFourDigitsstringOptional

Last 4 digits of the card.

Example: 0006
basketIdstringOptional

Basket ID.

Example: basketId
currencystringOptional

Currency of the payment.

Example: TRY
authCodestringOptional

Authorization code returned by the bank.

Example: 847162
phasestringOptional

Payment phase.

Example: AUTH
mdStatusinteger · enumOptional

3DS authentication result.

  • 1: Successful
  • 0,2-8: Failed
Example: 1Possible values:
hostReferencestringOptional

Host reference returned by the bank/acquirer.

Example: mock00001iyzihostrfn
signaturestringOptional

Signature value that can be used for verification.

Example: f95c9246235c30cad41169bb1df7381b7ffe42bf1ea1226c2dd211e83dfe40f7
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"
}

Sample Codes

Java

Json

Auth 3DS vs Auth v2 3DS

The payment/3dsecure/auth endpoint employs the standard 3D Secure 1.0 protocol, offering basic authentication with a simpler structure, making it easier for legacy systems to integrate. In contrast, the payment/v2/3dsecure/auth endpoint is built on the more advanced 3D Secure 2.0 protocol, which enhances security through richer data points for risk analysis and smoother integration with modern systems. While payment/3dsecure/auth is a reliable option for basic transactions, payment/v2/3dsecure/auth offers superior security, improved user experience, and better compliance with evolving payment regulations. We recommend transitioning to payment/v2/3dsecure/auth for these benefits.

PreviousInit 3DS
NextCheckout Form (CF)

Last updated