# Installment & BIN Service iyzico offers a convenient way to perform installment inquiries. API provides essential details such as the number of available installments, interest rates, and installment amounts as well as card characteristics like Issuer Bank, card family, card scheme. To obtain the desired information, simply include the required parameters in your request, and the API will respond with comprehensive installment details. {% hint style="success" %} Both Installment and BIN services provides card features on the responses. The major difference between two of services is installment service also includes installment rates. {% endhint %} ## Installment Service Request > The API provides installment counts, rates and amounts, as well as attributes such as issuing bank, card family and card scheme. It lists available installment options based on the given BIN and amount. You can also query installment rates with only the BIN or only the amount. ```json {"openapi":"3.0.3","info":{"title":"BIN and Installment","version":"1.0.0"},"servers":[{"url":"https://sandbox-api.iyzipay.com"}],"paths":{"/payment/iyzipos/installment":{"post":{"summary":"Installment Service Request","description":"The API provides installment counts, rates and amounts, as well as attributes such as issuing bank, card family and card scheme. It lists available installment options based on the given BIN and amount. You can also query installment rates with only the BIN or only the amount.","tags":["Installment"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstallmentRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstallmentResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header that starts with IYZWSv2 and contains a Base64-encoded signed hash.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"InstallmentRequest":{"type":"object","required":["price"],"properties":{"locale":{"type":"string","description":"Language preference used in requests and responses.","enum":["tr","en"]},"price":{"type":"number","format":"decimal","description":"Amount for installment calculation."},"binNumber":{"type":"string","description":"8-digit card BIN. If provided, suitability is returned per card/bank. If omitted, installment rates can be returned based on the amount only."},"conversationId":{"type":"string","description":"Request/response correlation ID. The value sent in the request is returned as-is in the response."}}},"InstallmentResponse":{"type":"object","properties":{"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID matching the request."},"installmentDetails":{"type":"array","description":"Installment options calculated according to BIN and amount.","items":{"$ref":"#/components/schemas/InstallmentDetail"}}}},"InstallmentDetail":{"type":"object","properties":{"binNumber":{"type":"string","description":"BIN used in the calculation."},"price":{"type":"number","format":"decimal","description":"Amount used in the calculation."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card scheme.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamilyName":{"type":"string","enum":["Bonus","Axess","World","Maximum","Paraf","Enpara Bank DC","QNB CC","QNB DC","Ziraat Bankası DC","BankkartCombo","Albaraka Türk DC","Vakıfbank DC","Neo","Paracard","TEB DC","Kuveyt Türk CC","Kuveyt Türk DC","Shop&Fly","Halkbank DC","Papara Card","Tlcard","Tosla","Bankamatik","ING Bank DC","Sipay DC","T.O.M.Kt.Bnk.A.Ş. CC","Turk Telekom","PTT DC","Miles&Smiles","Denizbank DC"],"description":"Card family."},"force3ds":{"type":"integer","description":"3DS requirement (0; No, 1; Yes).","enum":[0,1]},"bankCode":{"type":"integer","description":"Bank code."},"bankName":{"type":"string","description":"Bank name."},"forceCvc":{"type":"integer","description":"CVC requirement (0; No, 1; Yes).","enum":[0,1]},"commercial":{"type":"integer","description":"Commercial card flag (0; Personal, 1; Commercial).","enum":[0,1]},"dccEnabled":{"type":"integer","description":"DCC (Dynamic Currency Conversion) support (0; No, 1; Yes).","enum":[0,1]},"agricultureEnabled":{"type":"integer","description":"Agricultural card flag (0; No, 1; Yes).","enum":[0,1]},"installmentPrices":{"type":"array","description":"Installment options and prices.","items":{"$ref":"#/components/schemas/InstallmentPrice"}}}},"InstallmentPrice":{"type":"object","properties":{"installmentPrice":{"type":"number","format":"decimal","description":"Amount per installment."},"totalPrice":{"type":"number","format":"decimal","description":"Total amount with installments."},"installmentNumber":{"type":"integer","description":"Number of installments."}}},"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":"Correlation ID matching the request."}}}}}} ``` #### Sample Codes
PHP
Java
.Net
Python
Node.js
Postman
## BIN Service Request > Retrieves card attributes in BIN inquiries such as issuing bank, card family, and card scheme. To obtain the desired information, simply include the required parameters in your request. The API will respond with comprehensive details. ```json {"openapi":"3.0.3","info":{"title":"BIN and Installment","version":"1.0.0"},"servers":[{"url":"https://sandbox-api.iyzipay.com"}],"paths":{"/payment/bin/check":{"post":{"summary":"BIN Service Request","description":"Retrieves card attributes in BIN inquiries such as issuing bank, card family, and card scheme. To obtain the desired information, simply include the required parameters in your request. The API will respond with comprehensive details.","tags":["BIN"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BINCheckRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BINCheckResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"description":"Authorization header that starts with IYZWSv2 and contains a Base64-encoded signed hash.","schema":{"type":"string"}},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"description":"Content-Type value.","schema":{"type":"string"}}},"schemas":{"BINCheckRequest":{"type":"object","required":["binNumber"],"properties":{"locale":{"type":"string","description":"Language preference used in requests and responses.","enum":["tr","en"]},"binNumber":{"type":"string","description":"BIN to query (8 digits)."},"conversationId":{"type":"string","description":"Request/response correlation ID. The value sent in the request is returned as-is in the response."}}},"BINCheckResponse":{"type":"object","properties":{"binNumber":{"type":"string","description":"Queried BIN."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card scheme.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS","TROY"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","Enpara Bank DC","QNB CC","QNB DC","Ziraat Bankası DC","BankkartCombo","Albaraka Türk DC","Vakıfbank DC","Neo","Paracard","TEB DC","Kuveyt Türk CC","Kuveyt Türk DC","Shop&Fly","Halkbank DC","Papara Card","Tlcard","Tosla","Bankamatik","ING Bank DC","Sipay DC","T.O.M.Kt.Bnk.A.Ş. CC","Turk Telekom","PTT DC","Miles&Smiles","Denizbank DC"]},"bankName":{"type":"string","description":"Bank name."},"bankCode":{"type":"integer","description":"Bank code."},"commercial":{"type":"integer","description":"Commercial card flag (0; Personal, 1; Commercial).","enum":[0,1]},"status":{"type":"string","description":"Result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"Correlation ID matching the request."}}},"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":"Correlation ID matching the request."}}}}}} ``` #### Sample Codes
PHP
Java
.Net
Python
Node.js
Postman
### Remarkables According to the response provided by the service, following rules can be considered; * When the `card_type` parameter returns as `DEBIT_CARD`, It is suggested to use [3DS](https://docs.iyzico.com/en/payment-methods/api/3ds) payment method. * The installment options can be displayed on the frontend based on the values in the `card_family` field. The eligible card families for installment payments include: Bonus, World, Maximum, Axess, Cardfinans, Paraf, and Advantage. * If the `force3ds` value returns as `1`, means that the transaction must be processed [3DS](https://docs.iyzico.com/en/payment-methods/api/3ds). If it does as `0`, the transaction can be processed due to the preferences. If merchant account has [3DS](https://docs.iyzico.com/en/payment-methods/api/3ds) have set as mandatory, this value consistently returns `1`. * If the `BIN` number is not provided in the request, all available installment options will be displayed. However, if the `BIN` number is provided, the response will only include the installment options that are relevant and specific to that particular card. * The installment inquiry retrieves the installment rates defined in the "Installment and Commission Management" section of the iyzico merchant control panel. Any changes made in this section will automatically be reflected in the installment service.