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.

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.

Installment Service

Installment Service Request;

Installment Service Request

POST https://api.iyzipay.com/payment/iyzipos/installment

Request Body

Name	Type	Description
price*	String	Total amount for installment plans
binNumber	String	First 6 digits of card
locale	String	Language settings (default: tr)
conversationId	String	Conversation ID to match request and response

200: OK

Installment Service Response;

Parameters to be returned from the service are as follows:

Output Name	Type	Description
status	String	Service response result. (success / failure)
locale	String	Language settings (default: tr)
systemTime	Integer	Response system timestamp value
conversationId	String	If set, conversation ID to match request and response
binNumber(installmentDetails)	String	First 6 digits of card
price(installmentDetails)	String	Total amount of basket. Sum of basket items’ amounts must be equal to the total price of basket
cardType(installmentDetails)	String	Valid values are CREDIT_CARD, DEBIT_CARD, PREPAID_CARD
cardAssociation(installmentDetails)	String	Valid values are TROY, VISA, MASTER_CARD, AMERICAN_EXPRESS
cardFamilyName(installmentDetails)	String	Valid values are Bonus, Axess, World, Maximum, Paraf, CardFinans, Advantage
force3ds(installmentDetails)	String	Force 3D flag. If it returns 1, transaction must be processed with 3D Auth
bankName(installmentDetails)	String	Name of the issuer bank
bankCode(installmentDetails)	Integer	Bank code of the issuer bank
installmentPrice(installmentPrices)(installmentDetails)	String	Amount for per installment
totalPrice(installmentPrices)(installmentDetails)	String	Installment fee added to total amount
installmentNumber(installmentPrices)(installmentDetails)	String	Installment number
errorCode	String	Error code if service response status is failure
errorMessage	String	Error message if service response status is failure
errorGroup	String	Error group if service response status is failure

Sample Installment Request;

{
    "locale": "tr",
    "conversationId": "123456789",
    "binNumber": "454360",
    "price": "100.0"
}

Sample Installment Response;

{
    "status": "success",
    "locale": "tr",
    "systemTime": 1470727458044,
    "conversationId": "123456789",
    "installmentDetails": [
        {
            "binNumber": "454360",
            "price": 100,
            "cardType": "CREDIT_CARD",
            "cardAssociation": "VISA",
            "cardFamilyName": "Maximum",
            "force3ds": 0,
            "bankCode": 64,
            "bankName": "İş Bankası",
            "forceCvc": 0,
            "installmentPrices": [
                {
                    "installmentPrice": 100,
                    "totalPrice": 100,
                    "installmentNumber": 1
                },
                {
                    "installmentPrice": 50.68,
                    "totalPrice": 101.36,
                    "installmentNumber": 2
                },
                {
                    "installmentPrice": 33.95,
                    "totalPrice": 101.86,
                    "installmentNumber": 3
                },
                {
                    "installmentPrice": 17.43,
                    "totalPrice": 104.58,
                    "installmentNumber": 6
                },
                {
                    "installmentPrice": 12.19,
                    "totalPrice": 109.67,
                    "installmentNumber": 9
                }
            ]
        }
    ]
}

BIN Service

BIN Service Request;

BIN Service Request

POST https://api.iyzipay.com/payment/bin/check

Request Body

Name	Type	Description
binNumber*	String	First 6 digits of card
locale	String	Language settings (default: tr)
conversationId	String	Conversation ID to match request and response

200: OK

BIN Service Response;

Output Name	Type	Description
status	String	Service response result. (success / failure)
locale	String	Language settings (default: tr)
systemTime	Integer	Response system timestamp value
conversationId	String	If set, conversation ID to match request and response
binNumber	String	First 6 digits of card
cardType	String	Valid values are CREDIT_CARD, DEBIT_CARD, PREPAID_CARD
cardAssociation	String	Valid values are TROY, VISA, MASTER_CARD, AMERICAN_EXPRESS
cardFamilyName	String	Valid values are Bonus, Axess, World, Maximum, Paraf, CardFinans, Advantage
bankName	String	Name of the issuer bank
bankCode	Integer	Bank code of the issuer bank
commercial	integer	Defines if the card commercial or not. Parameter "1" addresses commercial cards while "0" personal.
errorCode	String	Error code if service response status is failure
errorMessage	String	Error message if service response status is failure
errorGroup	String	Error group if service response status is failure

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 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. If it does as 0, the transaction can be processed due to the preferences. If merchant account has 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.