# 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 > Finalizes the payment after successful 3D authentication. ```json {"openapi":"3.0.3","info":{"title":"3DS Payments","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/3dsecure/auth":{"post":{"summary":"Create 3DS Payment","description":"Finalizes the payment after successful 3D authentication.","tags":["3DS Payment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreeDSAuthRequest"}}}},"responses":{"200":{"description":"Successful response (payment completed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed Base64-encoded hash that starts with IYZWSv2.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"ThreeDSAuthRequest":{"type":"object","required":["paymentId"],"properties":{"locale":{"type":"string","description":"Language code. Default; tr","enum":["tr","en"]},"paymentId":{"type":"string","description":"Payment ID returned by the initialize call."},"conversationId":{"type":"string","description":"Unique ID for request/response correlation."},"conversationData":{"type":"string","description":"Data posted by the 3DS result. If present, it must be sent."}}},"PaymentResponse":{"type":"object","properties":{"status":{"type":"string","description":"It reports the result of the transaction. If the response returns success, it means the payment has been completed successfully.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language (tr/en)."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total charged amount."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status according to fraud filters.\n- 1: Approved\n- 0: Under review\n- -1: Declined\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s installment/commission rate (informational)."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s installment/commission amount (informational)."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee."},"cardType":{"type":"string","description":"Card type."},"cardAssociation":{"type":"string","description":"Card scheme/brand.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card product/family."},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency of the payment."},"itemTransactions":{"type":"array","description":"Line items per basket item.","items":{"type":"object","properties":{"paymentTransactionId":{"type":"string","description":"Line-item ID; must be stored by the merchant (used for refund/approve operations)."},"itemId":{"type":"string","description":"Merchant-defined item ID in the basket."},"price":{"type":"decimal","description":"Item price on merchant side."},"paidPrice":{"type":"decimal","description":"Collected amount allocated to this line item."},"transactionStatus":{"type":"integer","description":"Line item status.\n- 0: In fraud check\n- -1: Declined after fraud check\n- 1: Approved (Marketplace: Waiting for Merchant Approval)\n- 2: Approved (Marketplace approval given)\n","enum":[0,-1,1,2]},"blockageRate":{"type":"decimal","description":"Merchant blockage rate at line level."},"blockageRateAmountMerchant":{"type":"decimal","description":"Blockage amount reflected to the merchant."},"blockageResolvedDate":{"type":"string","description":"Blockage release date (yyyy-MM-dd HH:mm:ss)."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fee allocated to the line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission allocated to the line item."},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s commission rate allocated to the line item."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s commission amount allocated to the line item."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the merchant after fees/blocks."},"convertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Collected amount allocated to this line item."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fee allocated to the line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission allocated to the line item."},"blockageRateAmountMerchant":{"type":"decimal","description":"Merchant-side blockage amount."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the merchant after fees/blocks."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Converted amount produced by the rate."}}}}}},"authCode":{"type":"string","description":"Authorization code returned by the bank."},"phase":{"type":"string","description":"Payment phase."},"mdStatus":{"type":"integer","description":"3DS authentication result (1 means successful).","enum":[-1,0,1,2,3,4,5,6,7,8]},"hostReference":{"type":"string","description":"Host reference returned by the bank/acquirer."},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."}}}}}} ``` #### 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](/en/advanced/response-signature-validation.md), 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](/en/advanced/response-signature-validation.md), 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 > 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. ```json {"openapi":"3.0.3","info":{"title":"3DS v2 Payments","version":"1.0.2"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/v2/3dsecure/auth":{"post":{"summary":"Create 3DS v2 Payment","description":"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.","tags":["3DS Payment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreeDSV2AuthRequest"}}}},"responses":{"200":{"description":"Successful response (payment completed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreeDSV2PaymentResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header; a signed Base64-encoded hash that starts with IYZWSv2.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"ThreeDSV2AuthRequest":{"type":"object","required":["paymentId","paidPrice","basketId","currency"],"properties":{"locale":{"type":"string","enum":["tr","en"],"description":"Language code. Default; tr"},"paymentId":{"type":"string","description":"Payment ID returned after 3DS initialization."},"conversationId":{"type":"string","description":"Unique ID for request/response correlation."},"paidPrice":{"type":"decimal","description":"Collected amount to be used in 3DS v2 completion. Must match the paidPrice sent in INIT 3DS."},"basketId":{"type":"string","description":"Basket ID (must match INIT 3DS basketId)."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","NOK","CHF"],"description":"Currency. Default; TRY (must match the value sent in INIT 3DS)."}}},"ThreeDSV2PaymentResponse":{"type":"object","properties":{"status":{"type":"string","description":"It reports the result of the transaction. If the response returns success, it means the payment has been completed successfully.","enum":["success","failure"]},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total charged amount."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status according to fraud filters.\n- 1: Approved\n- 0: Under review\n- -1: Declined\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s installment/commission rate (informational)."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s installment/commission amount (informational)."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee."},"cardType":{"type":"string","description":"Card type."},"cardAssociation":{"type":"string","description":"Card scheme/brand.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card product/family."},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","description":"Currency of the payment."},"itemTransactions":{"type":"array","description":"Line items per basket item.","items":{"type":"object","properties":{"paymentTransactionId":{"type":"string","description":"Line-item ID; must be stored by the merchant (used for refund/approve operations)."},"itemId":{"type":"string","description":"Merchant-defined item ID in the basket."},"price":{"type":"decimal","description":"Item price on merchant side."},"paidPrice":{"type":"decimal","description":"Collected amount allocated to this line item."},"transactionStatus":{"type":"integer","description":"Line item status.\n- 0: In fraud check\n- -1: Declined after fraud check\n- 1: Approved (Marketplace: Waiting for Merchant Approval)\n- 2: Approved (Marketplace approval given)\n","enum":[0,-1,1,2]},"blockageRate":{"type":"decimal","description":"Merchant blockage rate at line level."},"blockageRateAmountMerchant":{"type":"decimal","description":"Blockage amount reflected to the merchant."},"blockageResolvedDate":{"type":"string","description":"Blockage release date (yyyy-MM-dd HH:mm:ss)."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fee allocated to the line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission allocated to the line item."},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s commission rate allocated to the line item."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s commission amount allocated to the line item."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the merchant after fees/blocks."},"convertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Collected amount allocated to this line item."},"iyziCommissionFee":{"type":"decimal","description":"iyzico fee allocated to the line item."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission allocated to the line item."},"blockageRateAmountMerchant":{"type":"decimal","description":"Merchant-side blockage amount."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be paid to the merchant after fees/blocks."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Converted amount produced by the rate."}}}}}},"authCode":{"type":"string","description":"Authorization code returned by the bank."},"phase":{"type":"string","description":"Payment phase."},"mdStatus":{"type":"integer","description":"3DS authentication result.\n- 1: Successful\n- 0,2-8: Failed\n","enum":[-1,0,1,2,3,4,5,6,7,8]},"hostReference":{"type":"string","description":"Host reference returned by the bank/acquirer."},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Timestamp (epoch ms)."},"conversationId":{"type":"string","description":"ID matching the request."}}}}}} ``` #### 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.
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.iyzico.com/en/payment-methods/api/3ds/3ds-implementation/auth-3ds.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.