# API - 3DS

## Initialize 3DS Payment

> Starts a 3D Secure session and returns an htmlContent value for 3DS 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/initialize":{"post":{"summary":"Initialize 3DS Payment","description":"Starts a 3D Secure session and returns an htmlContent value for 3DS authentication.","tags":["3DS Payment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreeDSInitializeRequest"}}}},"responses":{"200":{"description":"Successful response (3DS initialized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreeDSInitializeResponse"}}}},"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":{"ThreeDSInitializeRequest":{"type":"object","required":["price","paidPrice","callbackUrl","paymentCard","buyer","shippingAddress","billingAddress","basketItems"],"properties":{"locale":{"type":"string","description":"Language code. Default; tr","enum":["tr","en"]},"conversationId":{"type":"string","description":"Unique ID for request/response correlation."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Final amount to be charged to the customer."},"currency":{"type":"string","description":"Currency. Default; TRY.","enum":["TRY","USD","EUR","GBP","NOK","CHF"]},"installment":{"type":"integer","description":"Installment count (if omitted, a single installment is used).","enum":[1,2,3,4,6,9,12]},"paymentChannel":{"type":"string","description":"Payment channel.","enum":["WEB","MOBILE","MOBILE_WEB","MOBILE_IOS","MOBILE_ANDROID","MOBILE_WINDOWS","MOBILE_TABLET","MOBILE_PHONE"]},"basketId":{"type":"string","description":"Basket ID."},"paymentGroup":{"type":"string","description":"Payment group. Default; PRODUCT.","enum":["PRODUCT","LISTING","SUBSCRIPTION"]},"callbackUrl":{"type":"string","description":"Redirect URL after 3DS flow completes."},"paymentCard":{"description":"Card information.","$ref":"#/components/schemas/PaymentCard3DS"},"buyer":{"description":"Buyer information.","$ref":"#/components/schemas/Buyer3DS"},"shippingAddress":{"description":"Shipping address. Required if at least one basket item has itemType \"PHYSICAL\". If all items are \"VIRTUAL\", it is not required.","$ref":"#/components/schemas/Address"},"billingAddress":{"description":"Billing address.","$ref":"#/components/schemas/Address"},"basketItems":{"type":"array","description":"Basket items.","items":{"$ref":"#/components/schemas/BasketItem"}}}},"PaymentCard3DS":{"type":"object","required":["cardHolderName","cardNumber","expireYear","expireMonth","cvc"],"properties":{"cardHolderName":{"type":"string","description":"Cardholder’s full name."},"cardNumber":{"type":"string","description":"Card number (PAN)."},"expireYear":{"type":"string","description":"Expiration year (YY or YYYY)."},"expireMonth":{"type":"string","description":"Expiration month (MM)."},"cvc":{"type":"string","description":"Card security code."},"registerCard":{"type":"integer","description":"Save the card? (0 = no, 1 = yes)"}}},"Buyer3DS":{"type":"object","required":["id","name","surname","identityNumber","email","gsmNumber","registrationAddress","city","country"],"properties":{"id":{"type":"string","description":"Customer ID."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"Identity/ID number."},"email":{"type":"string","description":"Email address."},"gsmNumber":{"type":"string","description":"Mobile phone."},"registrationDate":{"type":"string","description":"Registration date (YYYY-MM-DD HH:mm:ss)."},"lastLoginDate":{"type":"string","description":"Last login date (YYYY-MM-DD HH:mm:ss)."},"registrationAddress":{"type":"string","description":"Registered address."},"city":{"type":"string","description":"City code/name."},"country":{"type":"string","description":"Country."},"zipCode":{"type":"string","description":"Postal code."},"ip":{"type":"string","description":"IP address."}}},"Address":{"type":"object","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Full address."},"zipCode":{"type":"string","description":"Postal code."},"contactName":{"type":"string","description":"Contact name."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"BasketItem":{"type":"object","required":["id","price","name","category1","itemType"],"properties":{"id":{"type":"string","description":"Item ID."},"price":{"type":"decimal","description":"Item price."},"name":{"type":"string","description":"Item name."},"category1":{"type":"string","description":"Main category."},"category2":{"type":"string","description":"Subcategory (optional)."},"itemType":{"type":"string","description":"Item type.","enum":["PHYSICAL","VIRTUAL"]},"subMerchantKey":{"type":"string","description":"Sub-merchant key for the service provider. Not sent in the standard business model; required only for marketplace model."},"subMerchantPrice":{"type":"string","description":"Amount to be transferred to the sub-merchant. Not sent in the standard business model; required only for marketplace model."}}},"ThreeDSInitializeResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","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."},"threeDSHtmlContent":{"type":"string","description":"Base64-encoded HTML content of the 3DS verification screen."},"paymentId":{"type":"string","description":"Unique paymentId returned by iyzico."},"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."}}}}}}
```

## 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."}}}}}}
```

## 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."}}}}}}
```


---

# 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/getting-started/preliminaries/api-reference-beta/payment-methods/api-3ds.md?ask=<question>
```

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.