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