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

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

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

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

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

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.

PreviousFraud Notifications NextRefund to Balance

Last updated 8 months ago