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 Request

post

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.

Header parameters

AuthorizationstringRequired

Authorization header that starts with IYZWSv2 and contains a Base64-encoded signed hash.

Example: IYZWSv2 aXBzaWduYXR1cmU...

Content-TypestringRequired

Content-Type value.

Example: application/json

Body

application/json

localestring · enumOptional

Language preference used in requests and responses.

Example: enPossible values:

pricenumber · decimalRequired

Amount for installment calculation.

Example: 100

binNumberstringOptional

8-digit card BIN. If provided, suitability is returned per card/bank. If omitted, installment rates can be returned based on the amount only.

Example: 54308100

conversationIdstringOptional

Request/response correlation ID. The value sent in the request is returned as-is in the response.

Example: 123456789

Responses

200

Successful response

application/json

statusstring · enumOptional

Result of the request.

Example: successPossible values:

localestringOptional

Response language.

Example: en

systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755547819061

conversationIdstringOptional

Correlation ID matching the request.

Example: 123456789

400

Error response

application/json

post

/payment/iyzipos/installment

HTTPcurl

POST https://sandbox-api.iyzipay.com/payment/iyzipos/installment
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib3gtcU43VzljOXI3aWhZZUs5Z2ZqbFhRWFlPUUZteEQyNkEmcmFuZG9tS2V5OjE3NTY0NjkyMjgyMzQxMjM0NTY3ODkmc2lnbmF0dXJlOmRmMzEwNjI2MTI0OGNhZTcxMDJlZDQxMjhjODA4MmIwOTlhMzU4OWNmZDc3MTNkODNlODk5YWEzMDg0NDBkZDg=
Content-Type: application/json

{
  "locale": "en",
  "price": 100.0,
  "binNumber": "54308100",
  "conversationId": "123456789"
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1755547819061,
  "conversationId": "123456789",
  "installmentDetails": [
    {
      "binNumber": "54308100",
      "price": 100,
      "cardType": "CREDIT_CARD",
      "cardAssociation": "MASTER_CARD",
      "cardFamilyName": "Paraf",
      "force3ds": 0,
      "bankCode": 12,
      "bankName": "Halkbank",
      "forceCvc": 0,
      "commercial": 0,
      "dccEnabled": 0,
      "agricultureEnabled": 0,
      "installmentPrices": [
        {
          "installmentPrice": 100,
          "totalPrice": 100,
          "installmentNumber": 1
        },
        {
          "installmentPrice": 51.61,
          "totalPrice": 103.22,
          "installmentNumber": 2
        },
        {
          "installmentPrice": 35.08,
          "totalPrice": 105.25,
          "installmentNumber": 3
        },
        {
          "installmentPrice": 18.7,
          "totalPrice": 112.22,
          "installmentNumber": 6
        },
        {
          "installmentPrice": 13.35,
          "totalPrice": 120.19,
          "installmentNumber": 9
        },
        {
          "installmentPrice": 10.77,
          "totalPrice": 129.2,
          "installmentNumber": 12
        }
      ]
    }
  ]
}

Sample Codes

PHP

Java

.Net

Python

Node.js

Postman

BIN Service Request

post

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.

Header parameters

AuthorizationstringRequired

Authorization header that starts with IYZWSv2 and contains a Base64-encoded signed hash.

Example: IYZWSv2 aXBzaWduYXR1cmU...

Content-TypestringRequired

Content-Type value.

Example: application/json

Body

application/json

localestring · enumOptional

Language preference used in requests and responses.

Example: enPossible values:

binNumberstringRequired

BIN to query (8 digits).

Example: 41579200

conversationIdstringOptional

Request/response correlation ID. The value sent in the request is returned as-is in the response.

Example: 1a2b3c4d5e6f

Responses

200

Successful response

application/json

binNumberstringOptional

Queried BIN.

Example: 46034500

cardTypestring · enumOptional

Card type.

Example: CREDIT_CARDPossible values:

cardAssociationstring · enumOptional

Card scheme.

Example: MASTER_CARDPossible values:

cardFamilystring · enumOptional

Card family.

Example: WorldPossible values:

bankNamestringOptional

Bank name.

Example: Vakıfbank

bankCodeintegerOptional

Bank code.

Example: 15

commercialinteger · enumOptional

Commercial card flag (0; Personal, 1; Commercial).

Example: 0Possible values:

statusstring · enumOptional

Result of the request.

Example: successPossible values:

localestringOptional

Response language.

Example: en

systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755547712091

conversationIdstringOptional

Correlation ID matching the request.

Example: 1a2b3c4d5e6f

400

Error response

application/json

post

/payment/bin/check

HTTPcurl

POST https://sandbox-api.iyzipay.com/payment/bin/check
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib3gtNE9hdVQwRX....cwZWMxZWIzZGU5Y2IwNTRkMjk4Zjc1NThlNmRiMmQwYTQ2NjA4NzJmYzY0NGFjNg==
Content-Type: application/json

{
  "locale": "en",
  "binNumber": "41579200",
  "conversationId": "1a2b3c4d5e6f"
}

{
  "binNumber": "41579200",
  "cardType": "CREDIT_CARD",
  "cardAssociation": "MASTER_CARD",
  "cardFamily": "World",
  "bankName": "Vakıfbank",
  "bankCode": 15,
  "commercial": 0,
  "status": "success",
  "locale": "en",
  "systemTime": 1755547712091,
  "conversationId": "1a2b3c4d5e6f"
}

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 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.