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.

If you want to see which card profiles support installments at your terminal before the buyer has entered a card (e.g., on a cart screen), see this endpoint’s sibling that doesn’t require a BIN: Installment Overview.

POST /v1/installment-options
Authorization: Bearer ldg_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.
baseAmount	No	The principal (sale) amount, an integer in minor units (kuruş) (≥1). If you send it, every option in the response carries an authoritative amount breakdown based on it; if you don’t, the response is just the rate matrix, as before.
customerCommissionShareBps	No	The commission share the customer bears, an integer in basis points (0-10000; 100% → 10000). Meaningful only together with baseAmount. When omitted, the default depends on the basis: on a gross basis the share is taken as 0 (no commission is passed to the customer); on a net-basis terminal the share is 10000 (full pass-through) — the net basis passes the entire commission to the customer by definition.

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

customerCommissionShareBps cannot be sent alone

customerCommissionShareBps is a share of a commission, and a share only applies to a base amount (baseAmount). If you send customerCommissionShareBps without baseAmount, the request is rejected with 400 validation_error; the field is not silently ignored.

Response

200 OK:

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

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.
commissionBasis	Your terminal’s commission basis, gross or net. Always returned, regardless of whether you sent baseAmount in the request. See Pricing guide.
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.
options[].baseAmount	The baseAmount you sent in the request; the same value on every option. null if you didn’t send baseAmount.
options[].commissionAmount	The total commission calculated for this installment count (kuruş), computed according to your terminal’s commissionBasis. null if you didn’t send baseAmount.
options[].customerShareAmount	The share of that commission passed to the customer according to customerCommissionShareBps (kuruş); equal to totalAmount − baseAmount. null if you didn’t send baseAmount.
options[].totalAmount	The final amount to charge the customer (kuruş). Authoritative; see Authoritative amount breakdown with baseAmount. null if you didn’t send baseAmount.

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.

Authoritative amount breakdown with baseAmount

If you send baseAmount in the request, you don’t have to do the math yourself: every option in options comes with a complete amount breakdown for that installment count.

{
  "bin": "41551400",
  "terminalId": "trm_3Kd9x",
  "baseAmount": 10000,
  "customerCommissionShareBps": 0
}

200 OK:

{
  "cardBrand": "world",
  "cardFamily": "credit",
  "cardBank": "Example Bank",
  "options": [
    { "installmentCount": 1, "rateBps": 250, "fixedFee": null,
      "baseAmount": 10000, "commissionAmount": 250, "customerShareAmount": 0, "totalAmount": 10000 },
    { "installmentCount": 3, "rateBps": 180, "fixedFee": null,
      "baseAmount": 10000, "commissionAmount": 180, "customerShareAmount": 0, "totalAmount": 10000 },
    { "installmentCount": 6, "rateBps": 220, "fixedFee": null,
      "baseAmount": 10000, "commissionAmount": 220, "customerShareAmount": 0, "totalAmount": 10000 }
  ],
  "commissionBasis": "gross"
}

In this example customerCommissionShareBps is sent as 0, so you bear the full commission: customerShareAmount is zero and totalAmount stays equal to the baseAmount you sent. If you send a positive customerCommissionShareBps, that share is reflected in customerShareAmount and totalAmount rises above baseAmount — the calculation is done for you, according to your terminal’s commissionBasis.

totalAmount is authoritative

You can send totalAmount directly as the amount field of POST /v1/payments. If you recompute this value yourself, any rounding difference lands in your own net payout; the totalAmount this endpoint returns always gives the correct result.

The response is additive, but not byte-identical

commissionBasis now appears in every response, and every option carries four new fields (baseAmount, commissionAmount, customerShareAmount, totalAmount). Unless you send baseAmount, these four fields come back null and your existing integration is unaffected — but the response is no longer byte-identical to before. If your JSON parser ignores unknown/null fields, this doesn’t cause a problem.

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 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. Which amount the rate is calculated on depends on your terminal’s commission basis: the commissionBasis field in the response (gross or net) tells you which one applies. On a gross basis (today’s default behavior), the rate is calculated on the amount charged to the buyer; on a net basis, the rate is calculated on the principal, and the customer’s share is added on top of the principal. 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 amount that covers the commission, and send that higher amount in POST /v1/payments’s amount field.

You don’t have to do this math by hand: if you add baseAmount (and, optionally, customerCommissionShareBps) to the request, this endpoint returns an authoritative amount breakdown and you can send totalAmount directly. The manual calculation below shows how to apply the simplest policy — passing the commission through one-to-one — yourself, on a gross-basis terminal; because the rate is calculated on the principal instead, this formula does not apply on a net-basis terminal — use the authoritative breakdown there instead.

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.

Example: integer-kuruş math (no floats, gross basis)

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); on this endpoint the response carries no Retry-After header — wait a short while and retry.

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.