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:

Auth 3DS Request

POST https://api.iyzipay.com/payment/3dsecure/auth

Request Body

Name	Type	Description
locale	String	Language (default: tr)
conversationId	String	Conversation ID to match request and response
paymentId*	String	ID of the payment. Merchants should keep payment ID in their system (this ID will be used for cancel requests)
conversationData	String	ConversationData value you will obtain from the 3D return link adress. If this parameter has returned with a value, it should be added in the 3D payment query.

200: OK

Auth 3DS Response

Output Name	Type	Description
status	String	Service response result (success / failure)
errorCode	String	Error code if service response status is failure
errorMessage	String	Error message if service response status is failure
errorGroup	String	Error group if service response status is failure
locale	String	Language (default: tr)
systemTime	Long	Response system timestamp value
conversationId	String	If set, conversation ID to match request and response
paymentId	String	ID of the payment. Merchants should keep payment ID in their system (this ID will be used for cancel requests)
price	Decimal	Total amount of basket. The sum of basket items’ amount must be equal to the price of basket
paidPrice	Decimal	Final amount (including installment fee) that will be charged to customer’s card. Merchants should store this value in their system
currency	String	Currency of request
installment	Integer	Installment number of payment, for single payments it returns 1. Valid values are 1, 2, 3, 6, 9, 12
basketId	String	Merchant's basket ID
binNumber	String	First 6 digit of card
cardAssociation	String	Valid values are VISA, MASTER_CARD, AMERICAN_EXPRESS, TROY
cardFamily	String	Valid values are Bonus, Axess, World, Maximum, Paraf, CardFinans, Advantage
cardType	String	Valid values are CREDIT_CARD, DEBIT_CARD, PREPAID_CARD
fraudStatus	Integer	Fraud risk status for payment request (0 for review / 1 for accept)
iyziCommissionFee	Decimal	iyzico commission fee for payment transaction
iyziCommissionRateAmount	Decimal	iyzico commission rate amount for payment transaction
merchantCommissionRate	Decimal	Merchant commission rate (e.g. price=100 & paidPrice=110, then merchant commission rate = 10)
merchantCommissionRateAmount	Decimal	Merchant commission rate amount (e.g. price=100 & paidPrice=110, then merchant commission rate amount = 10)
paymentTransactionId (ItemTransactions)	String	ID of basket item. Merchants should keep payment ID in their system (this ID will be used for cancel requests)
itemId(ItemTransactions)	String	Item ID of each item in basket
price(ItemTransactions)	Decimal	Item price of each item in basket
paidPrice(ItemTransactions)	Decimal	Captured amount from card based on each item. Merchants should keep paidPrice in their system
transactionStatus (ItemTransactions)	Integer	Status of a payment transaction. (0 for waiting / -1 for rejected by fraud / 1 for waiting for approval / 2 for approved
blockageRate(ItemTransactions)	Decimal	Blockage rate based on each item.
blockageRateAmountMerchant(ItemTransactions)	Decimal	Blockage rate amount for merchant based on each item
blockageResolvedDate(ItemTransactions)	String	Blockage resolve date based on each item. Date format should be “2015-10-19 14:36:52”
iyziCommissionFee(ItemTransactions)	Decimal	iyzico commission fee based on each item
iyziCommissionRateAmount(ItemTransactions)	Decimal	iyzico commission rate amount based on each item
merchantCommissionRate(ItemTransactions)	Decimal	Merchant commission rate (e.g. price=100 & paidPrice=110, then merchant commission rate = 10)
merchantCommissionRateAmount(ItemTransactions)	Decimal	Merchant commission rate amount (e.g. price=100 & paidPrice=110, then merchant commission rate amount = 10)
merchantPayoutAmount(ItemTransactions)	Decimal	Payout amount for each item transaction. This is the amount that remains after after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions)
paidPrice(ItemTransactions)(convertedPayout)	Decimal	Converted charged amount to card based on each item. Merchants should keep paidPrice in their system.
iyziCommissionFee(ItemTransactions)(convertedPayout)	Decimal	Converted iyzico commission fee based on each item
iyziCommissionRateAmount(ItemTransactions)(convertedPayout)	Decimal	Converted iyzico commission rate amount based on each item
blockageRateAmountMerchant(ItemTransactions)(convertedPayout)	Decimal	Converted blockage rate amount for merchant based on each item
merchantPayoutAmount(ItemTransactions)(convertedPayout)	Decimal	Converted payout amount for each item transaction. This the amount that remains after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions)
iyziConversationRate(ItemTransactions)(convertedPayout)	Decimal	iyzico conversation rate
iyziConversationRateAmount(ItemTransactions)(convertedPayout)	Decimal	iyzico conversation rate amount
currency(ItemTransactions)(convertedPayout)	String	Currency for payout conversion

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:

POST https://api.iyzipay.com/payment/v2/3dsecure/auth

Request Body

Name	Type	Description
locale	String	Language (default: tr)
conversationId	String	Conversation ID to match request and response
paymentId*	String	ID of the payment. Merchants should keep payment ID in their system (this ID will be used for cancel requests)
paidPrice*	String	Final amount (including installment fee) that was charged to customer’s card
basketId*	String	Merchant's basket ID
currency*	String	Currency of the payment (default: TRY). Alternatively, you can set USD, EUR, GBP and IRR

200: OK

Auth 3DS Response

Output Name	Type	Description
status	String	Service response result (success / failure)
errorCode	String	Error code if service response status is failure
errorMessage	String	Error message if service response status is failure
errorGroup	String	Error group if service response status is failure
locale	String	Language (default: tr)
systemTime	Long	Response system timestamp value
conversationId	String	If set, conversation ID to match request and response
paymentId	String	ID of the payment. Merchants should keep payment ID in their system (this ID will be used for cancel requests)
price	Decimal	Total amount of basket. The sum of basket items’ amount must be equal to the price of basket
paidPrice	Decimal	Final amount (including installment fee) that will be charged to customer’s card. Merchants should store this value in their system
currency	String	Currency of request
installment	Integer	Installment number of payment, for single payments it returns 1. Valid values are 1, 2, 3, 6, 9, 12
basketId	String	Merchant's basket ID
binNumber	String	First 6 digit of card
cardAssociation	String	Valid values are VISA, MASTER_CARD, AMERICAN_EXPRESS, TROY
cardFamily	String	Valid values are Bonus, Axess, World, Maximum, Paraf, CardFinans, Advantage
cardType	String	Valid values are CREDIT_CARD, DEBIT_CARD, PREPAID_CARD
fraudStatus	Integer	Fraud risk status for payment request (0 for review / 1 for accept)
iyziCommissionFee	Decimal	iyzico commission fee for payment transaction
iyziCommissionRateAmount	Decimal	iyzico commission rate amount for payment transaction
merchantCommissionRate	Decimal	Merchant commission rate (e.g. price=100 & paidPrice=110, then merchant commission rate = 10)
merchantCommissionRateAmount	Decimal	Merchant commission rate amount (e.g. price=100 & paidPrice=110, then merchant commission rate amount = 10)
paymentTransactionId (ItemTransactions)	String	ID of basket item. Merchants should keep payment ID in their system (this ID will be used for cancel requests)
itemId(ItemTransactions)	String	Item ID of each item in basket
price(ItemTransactions)	Decimal	Item price of each item in basket
paidPrice(ItemTransactions)	Decimal	Captured amount from card based on each item. Merchants should keep paidPrice in their system
transactionStatus (ItemTransactions)	Integer	Status of a payment transaction. (0 for waiting / -1 for rejected by fraud / 1 for waiting for approval / 2 for approved
blockageRate(ItemTransactions)	Decimal	Blockage rate based on each item.
blockageRateAmountMerchant(ItemTransactions)	Decimal	Blockage rate amount for merchant based on each item
blockageResolvedDate(ItemTransactions)	String	Blockage resolve date based on each item. Date format should be “2015-10-19 14:36:52”
iyziCommissionFee(ItemTransactions)	Decimal	iyzico commission fee based on each item
iyziCommissionRateAmount(ItemTransactions)	Decimal	iyzico commission rate amount based on each item
merchantCommissionRate(ItemTransactions)	Decimal	Merchant commission rate (e.g. price=100 & paidPrice=110, then merchant commission rate = 10)
merchantCommissionRateAmount(ItemTransactions)	Decimal	Merchant commission rate amount (e.g. price=100 & paidPrice=110, then merchant commission rate amount = 10)
merchantPayoutAmount(ItemTransactions)	Decimal	Payout amount for each item transaction. This is the amount that remains after after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions)
paidPrice(ItemTransactions)(convertedPayout)	Decimal	Converted charged amount to card based on each item. Merchants should keep paidPrice in their system.
iyziCommissionFee(ItemTransactions)(convertedPayout)	Decimal	Converted iyzico commission fee based on each item
iyziCommissionRateAmount(ItemTransactions)(convertedPayout)	Decimal	Converted iyzico commission rate amount based on each item
blockageRateAmountMerchant(ItemTransactions)(convertedPayout)	Decimal	Converted blockage rate amount for merchant based on each item
merchantPayoutAmount(ItemTransactions)(convertedPayout)	Decimal	Converted payout amount for each item transaction. This the amount that remains after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions)
iyziConversationRate(ItemTransactions)(convertedPayout)	Decimal	iyzico conversation rate
iyziConversationRateAmount(ItemTransactions)(convertedPayout)	Decimal	iyzico conversation rate amount
currency(ItemTransactions)(convertedPayout)	String	Currency for payout conversion

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.