# Init 3DS [Init 3DS](/en/payment-methods/api/3ds/3ds-implementation/init-3ds.md) API is responsible for processing the customer's card payments with 3DS. As like Its ancestor [NON-3DS](/en/payment-methods/api/non-3ds.md); * It supports transactions made with TROY, MASTERCARD, VISA, and AMEX branded cards. * For cards participating in installment programs such as BONUS, WORLD, MAXIMUM, AXESS, CARDFINANS, PARAF, and ADVANTAGE, the service allows options for 2, 3, 6, 9, and 12 installments. * Successful transactions are displayed in green, while failed transactions are displayed in red on the panel. * The merchant can utilize the conversationId and basketId parameters as order numbers on their side. By incorporating these features, you can provide a seamless payment experience for your customers, with real-time feedback on the success or failure of their transactions. ## 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."}}}}}} ``` #### Sample Codes
PHP
Java
.Net
Node.Js
Python
Postman

Lastly analyzing following headlines, you can effectively handle and respond to the outcome of the payment inquiry, ensuring a smooth and reliable payment process for your customers. * The `status` parameter provides information about the status of the transaction. `success` indicates that the transaction has been successfully completed and the payment has been processed. `failure` indicates that the transaction has failed, and an error message related to the failure reason is provided. * The `paymentStatus` parameter is null for this service. * The `paymentId` and `paymentTransactionId` values should be stored for future reference and tracking. * In the event of a failed transaction (`failure` status), the `errorCode`, `errorMessage`, and `errorGroup` parameters will be returned with corresponding values, providing details about the error. --- # 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/init-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.