Installment Options

You look up the installment options available at a terminal, and the commission rate you would pay for each one, by sending the card’s first 8 digits (BIN) and the target terminal. Use this call before creating a payment, to show installment options to the buyer on your own checkout and decide whether to pass the commission on to the sale price. It also shows, ahead of time, which installment counts creating a payment will accept, so you avoid a late error after the payment is already underway.

POST /v1/installment-options
Authorization: Bearer ptk_live_…
Content-Type: application/json

Request body

{
  "bin": "41551400",
  "terminalId": "trm_3Kd9x"
}

Field	Required	Description
bin	Yes	The card’s first 8 digits — not the full PAN. Must be exactly 8 digits; 6-7 digits or 9+ digits are rejected with validation_error (400).
terminalId	Yes	The terminal to query. Must belong to you and be active; otherwise terminal_not_allowed is returned.

Why exactly 8 digits

Do not send 6 or 7 digits: the bin field is validated against an exact 8-digit pattern, and a shorter or longer input does not silently resolve the brand as “unknown” (cardBrand: null) — it is rejected with validation_error (400) instead. The guard exists to prevent the preview from this endpoint from silently resolving to the wrong brand and diverging from the real outcome you get when you create a payment with the same card. Call this endpoint once the card’s 8th digit has been entered (not the 6th).

Response

200 OK:

{
  "cardBrand": "world",
  "cardFamily": "credit",
  "cardBank": "Example Bank",
  "options": [
    { "installmentCount": 1, "rateBps": 250, "fixedFee": null },
    { "installmentCount": 3, "rateBps": 180, "fixedFee": null },
    { "installmentCount": 6, "rateBps": 220, "fixedFee": null }
  ]
}

Field	Description
cardBrand	The card’s installment/loyalty brand (e.g., world, paraf, bonus, maximum, axess, advantage, cardfinans, saglam, vkart, bankkart). null if the BIN could not be resolved or the brand is unknown.
cardFamily	The card family (credit, debit, prepaid, foreign). null if the BIN could not be resolved at all.
cardBank	The issuing bank’s name (if known); not PII. null if unknown.
options	The list of installment × rate combinations that can actually be charged for this card × terminal pair, sorted ascending by installment count. Includes the cash option (installmentCount: 1) when the terminal’s effective installment set includes it. The list can come back empty; see An empty options list.
options[].installmentCount	Number of installments; 1 for a single charge.
options[].rateBps	The total (sale) commission rate for this installment count, as an integer in basis points (2.5% → 250).
options[].fixedFee	The fixed fee for this installment count, an integer in minor units (kuruş); null if none.

If the terminal’s PSP does not support installments for the card, or the brand is unknown

options contains only the cash entry (installmentCount: 1), when the effective set includes it. This happens when the card’s brand is not part of the PSP’s installment program, the brand could not be resolved, or the PSP limits installments to cards it issues itself and this card was not issued by that PSP. In this case, do not offer installments on your checkout — only a cash charge is possible.

A terminal’s effective installment set can be narrowed

The installment counts a terminal accepts on your account may be narrowed to a subset of the ceiling the bank allows (this configuration is done in the Lydia Gate Merchant Panel). When that is the case, options lists only the installment counts within that narrowed set. If you add your own allowedInstallmentCounts restriction when creating a payment link, the final set offered to the buyer is the intersection of the card’s installment brand scope, the terminal’s (possibly narrowed) set, and the link’s restriction.

PSP cost/margin is never returned

rateBps and fixedFee carry only the total sale commission rate you would pay Lydia Gate at this terminal. Lydia Gate’s own cost/margin structure never appears in this response.

An empty options list: you cannot charge this card

options can come back as an empty array, which means no option at all — including the cash option (installmentCount: 1) — is available for this card × terminal pair. The most common cause is that the bank connection (virtual POS) backing your terminal does not support the card’s type; in practice you see this most often with foreign-issued cards (cardFamily: "foreign"). (The list also stays empty when your terminal’s effective installment set excludes the cash option and the card is not eligible for installments.)

When you get an empty list, do not try to charge this card on this terminal; ask the buyer for another card. If you try anyway, the payment is rejected with virtual_pos_card_type_not_supported (422) or installment_not_allowed (422) — see Error Codes. A rejection caused by an unsupported card type draws down the payment’s card attempt allowance; see Payment Flow.

How this endpoint relates to creating a payment

Every installmentCount this endpoint returns is accepted with the same rateBps/fixedFee when you create a payment (the installment field of POST /v1/payments) with the same terminal and BIN. If you send an installment value it did not return, you get installment_not_allowed (422) at create time if your terminal has no permission for it, or otherwise (for reasons that depend on the card’s brand) during the payment’s 3D relay — see Error Codes: installment mismatch.

The list is card-specific: an installment count your terminal allows in general may be absent for a particular card. For that reason, do not hardcode the installment menu on your checkout; call this endpoint for every card and render the list it returns as-is. Every installment count you see in the list is chargeable, and every one you do not see is not.

Pricing guide: passing the commission on to your sale price

This endpoint tells you the total commission rate that applies at your terminal, per installment count. With this information, you have two choices:

1. You absorb the commission: you charge the buyer the same amount (amount) regardless of installment count; Lydia Gate deducts its commission from your net payout.
2. You pass the commission on to the buyer (installment surcharge): on an installment sale, you charge the buyer a higher gross amount that covers the commission, and send that higher amount in POST /v1/payments’s amount field. Lydia Gate always calculates its commission on the gross amount you send — adding a surcharge to the gross does not change how the commission is calculated, it only grows the base the commission is calculated on.

You decide the surcharge rate freely, according to your own commercial policy; rateBps only tells you the commission you would pay — it does not constrain what you charge the buyer. The example below shows the simplest policy: passing the commission through one-to-one.

Example: integer-kuruş math (no floats)

Say your cash sale price is 100.00 TRY (amount = 10000 kuruş) and the buyer selects 3 installments; assume this endpoint returned rateBps: 180 (1.80%) for installmentCount: 3. If you decide to pass the commission through one-to-one as a surcharge:

surcharge = (cashAmount * rateBps) / 10000   // integer division: 10000 * 180 / 10000 = 180 kuruş
grossAmount = cashAmount + surcharge          // 10000 + 180 = 10180 kuruş

You send 10180 in your POST /v1/payments call’s amount field.

Rounding: nearest kuruş (half-up)

Lydia Gate rounds commission to the nearest kuruş (half-up; an exact .5 fraction rounds up). Do not use floats/decimals in your own surcharge calculation; prefer integer-kuruş arithmetic as shown above — float multiplication can produce rounding errors. See Amounts and Currency.

Rate limit

A per-minute rate limit applies per partner (you may call this frequently as the buyer types the BIN on your checkout; a ceiling still applies against BIN scanning/probing). If exceeded, you get rate_limited (429); the response may carry a Retry-After header.

Possible errors

Code	HTTP	Reason
validation_error	400	bin is not exactly 8 digits, or terminalId is blank/missing.
terminal_not_allowed	403	The terminal does not belong to you, is inactive, or the card’s family is not allowed at this terminal.
rate_limited	429	Too many requests: the rate limit was exceeded.

Full list: Error Codes.

Rare case: configuration gap

If your terminal has no active cash commission rate configured for the resolved card type (a configuration gap), this endpoint returns commission_rate_not_found with a 500 status. This is not a client error; if it happens, contact support.