Installment Overview

Before the buyer has entered a card — for example, on a cart or pre-checkout summary screen — you send the target terminal and look up every installment option currently available at that terminal, grouped by card profile, along with the most expensive option for each installment count. This endpoint is the sibling of Installment Options that does not require a card’s BIN: it answers “which card types support installments at this terminal” before you know the card’s brand or type.

Because this endpoint never sees the card, it cannot tell you which of the returned groups will actually apply to the buyer’s card — it only lists every profile that is theoretically possible at your terminal. Once the buyer has entered the card’s first 8 digits, switch to Installment Options for the authoritative answer.

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

Request body

{
  "terminalId": "trm_3Kd9x"
}

Field	Required	Description
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 carries an authoritative amount breakdown and the “most expensive” criterion in maximums switches to amount; if you don’t, the criterion is rate.
customerCommissionShareBps	No	The commission share the customer bears, an integer in basis points (0-10000). Meaningful only together with baseAmount. The default behavior matches Installment Options: 0 on a gross basis, 10000 (full pass-through) on a net-basis terminal.

customerCommissionShareBps cannot be sent alone

If you send customerCommissionShareBps without baseAmount, the request is rejected with 400 validation_error; the field is not silently ignored.

Response

200 OK:

{
  "commissionBasis": "gross",
  "maximums": [
    { "option": { "installmentCount": 1, "rateBps": 250, "fixedFee": null,
        "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null },
      "source": { "cardType": "credit", "onUs": false, "cardBrand": null } },
    { "option": { "installmentCount": 3, "rateBps": 180, "fixedFee": null,
        "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null },
      "source": { "cardType": null, "onUs": null, "cardBrand": "paraf" } },
    { "option": { "installmentCount": 6, "rateBps": 220, "fixedFee": null,
        "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null },
      "source": { "cardType": null, "onUs": null, "cardBrand": "paraf" } }
  ],
  "optionGroups": [
    { "cardType": "credit", "onUs": false, "cardBrand": null, "onUsRequired": null,
      "options": [ { "installmentCount": 1, "rateBps": 250, "fixedFee": null,
          "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null } ] },
    { "cardType": "credit", "onUs": true, "cardBrand": null, "onUsRequired": null,
      "options": [ { "installmentCount": 1, "rateBps": 200, "fixedFee": null,
          "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null } ] },
    { "cardType": "debit", "onUs": false, "cardBrand": null, "onUsRequired": null,
      "options": [ { "installmentCount": 1, "rateBps": 150, "fixedFee": 50,
          "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null } ] },
    { "cardType": "debit", "onUs": true, "cardBrand": null, "onUsRequired": null,
      "options": [ { "installmentCount": 1, "rateBps": 150, "fixedFee": 50,
          "baseAmount": null, "commissionAmount": null, "customerShareAmount": null, "totalAmount": null } ] },
    { "cardType": null, "onUs": null, "cardBrand": "paraf", "onUsRequired": true,
      "options": [
        { "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 }
      ] }
  ]
}

In this example the terminal accepts credit and debit cards; on credit cards, the terminal’s own bank applies a lower rate (200) to its own cards (onUs: true) than to other banks’ cards (onUs: false, 250). On paraf-branded cards, installments are only available on cards issued by the terminal’s own bank (onUsRequired: true).

Field	Description
commissionBasis	Your terminal’s commission basis, gross or net. Always returned, regardless of whether you sent baseAmount.
maximums	The single most expensive option per installment count, together with the card profile that produced it (source); sorted ascending by installmentCount. See the criterion below.
maximums[].option	The installment × rate row — the same shape as the options[] row on Installment Options (installmentCount/rateBps/fixedFee plus the authoritative breakdown if you sent baseAmount).
maximums[].source	The card profile that produced this row (cardType/onUs/cardBrand); see the profile definition below.
optionGroups	One group per applicable card profile at your terminal; an empty group is never returned.
optionGroups[].cardType	The card type (credit, debit, prepaid, foreign); null if this dimension does not distinguish the group (as in brand groups).
optionGroups[].onUs	Whether the card is issued by the terminal’s own bank (true) or by another bank (false); null if this dimension does not apply.
optionGroups[].cardBrand	The installment brand (world, paraf, bonus, maximum, axess, advantage, cardfinans, saglam, vkart, bankkart); null if brand is not the deciding factor for this group.
optionGroups[].onUsRequired	Set only on brand groups (cardType: null) — see How to read onUsRequired.
optionGroups[].options	The installment × rate rows for this profile, sorted ascending by installmentCount.

Brand does not always decide the rate on DEBIT/PREPAID/FOREIGN

When a brand group’s cardType is debit, prepaid, or foreign, the brand only decides which installment counts are offered — the applied rate can come from the card’s type rather than its brand. In that case, the same installment count appears in both the branded and non-branded group with an equal rate; you can display either.

How “most expensive” is decided

For each installment count in maximums, the criterion depends on your request:

• If you sent baseAmount: the highest customerShareAmount (≡ totalAmount) wins.
• If you didn’t send baseAmount: the highest rateBps wins; ties are broken by the larger fixedFee (since fixedFee can vary per row, this criterion is an amount-independent approximation).

onUsRequired is a non-binding hint

onUsRequired: true means “this brand’s installments are only available on cards issued by your terminal’s own bank” — but it is a hint, not a binding rule, and can be ignored. Whether a given card is actually eligible is only known for certain once you have the card and query Installment Options; on your checkout, use this field only for an informational note such as “only on [bank]’s own cards” — don’t pre-filter your installment menu based on it.

Coverage guarantee and unknown BINs

Every card profile group this endpoint returns covers every option Installment Options can return for a resolvable BIN, and never exceeds maximums for that installment count. In other words: if a card’s BIN is known to us, every row you would get from the BIN-based endpoint for that card appears here, in the matching profile group, with identical values.

The one exception: an unresolved BIN

If a card’s BIN is not known to us, the BIN-based endpoint assumes the card is a credit card not issued by the terminal’s own bank (onUs: false) and returns only the cash rate for that assumption. Because this overview endpoint never sees the card, it does not represent that assumption — this row is not separately listed here. When the card’s BIN is known and your terminal accepts credit cards, these two rows usually coincide, but this is not guaranteed.

Empty lists: no card profile can be offered yet

Both maximums and optionGroups can come back empty, meaning no card profile — including cash — can be offered installments at this terminal right now. The most common causes are: the bank connection backing your terminal is inactive, your terminal’s commission basis is net but the conditions net basis needs (a direct-collection connection plus commission reporting to the bank) are not met right now — the BIN-based endpoint returns empty in that case too; note that sending a partial customerCommissionShareBps on a net terminal never yields an empty list, it always fails with 422 commission_share_not_applicable (see Possible errors) — or no card family at all is allowed at your terminal. When you get an empty response, do not offer installments on your checkout.

Authoritative amount breakdown with baseAmount

If you send baseAmount in the request, you don’t have to do the math yourself — the same breakdown logic as Installment Options applies here: every option carries commissionAmount/customerShareAmount/totalAmount, and totalAmount is authoritative.

{
  "terminalId": "trm_3Kd9x",
  "baseAmount": 10000,
  "customerCommissionShareBps": 10000
}

200 OK (the same scenario as above, with baseAmount = 10000 and customerCommissionShareBps = 10000):

{
  "commissionBasis": "gross",
  "maximums": [
    { "option": { "installmentCount": 1, "rateBps": 250, "fixedFee": null,
        "baseAmount": 10000, "commissionAmount": 256, "customerShareAmount": 257, "totalAmount": 10257 },
      "source": { "cardType": "credit", "onUs": false, "cardBrand": null } },
    { "option": { "installmentCount": 3, "rateBps": 180, "fixedFee": null,
        "baseAmount": 10000, "commissionAmount": 183, "customerShareAmount": 184, "totalAmount": 10184 },
      "source": { "cardType": null, "onUs": null, "cardBrand": "paraf" } },
    { "option": { "installmentCount": 6, "rateBps": 220, "fixedFee": null,
        "baseAmount": 10000, "commissionAmount": 225, "customerShareAmount": 225, "totalAmount": 10225 },
      "source": { "cardType": null, "onUs": null, "cardBrand": "paraf" } }
  ],
  "optionGroups": [
    { "cardType": "credit", "onUs": false, "cardBrand": null, "onUsRequired": null,
      "options": [ { "installmentCount": 1, "rateBps": 250, "fixedFee": null,
          "baseAmount": 10000, "commissionAmount": 256, "customerShareAmount": 257, "totalAmount": 10257 } ] },
    { "cardType": "credit", "onUs": true, "cardBrand": null, "onUsRequired": null,
      "options": [ { "installmentCount": 1, "rateBps": 200, "fixedFee": null,
          "baseAmount": 10000, "commissionAmount": 204, "customerShareAmount": 205, "totalAmount": 10205 } ] },
    { "cardType": "debit", "onUs": false, "cardBrand": null, "onUsRequired": null,
      "options": [ { "installmentCount": 1, "rateBps": 150, "fixedFee": 50,
          "baseAmount": 10000, "commissionAmount": 203, "customerShareAmount": 204, "totalAmount": 10204 } ] },
    { "cardType": "debit", "onUs": true, "cardBrand": null, "onUsRequired": null,
      "options": [ { "installmentCount": 1, "rateBps": 150, "fixedFee": 50,
          "baseAmount": 10000, "commissionAmount": 203, "customerShareAmount": 204, "totalAmount": 10204 } ] },
    { "cardType": null, "onUs": null, "cardBrand": "paraf", "onUsRequired": true,
      "options": [
        { "installmentCount": 3, "rateBps": 180, "fixedFee": null,
          "baseAmount": 10000, "commissionAmount": 183, "customerShareAmount": 184, "totalAmount": 10184 },
        { "installmentCount": 6, "rateBps": 220, "fixedFee": null,
          "baseAmount": 10000, "commissionAmount": 225, "customerShareAmount": 225, "totalAmount": 10225 }
      ] }
  ]
}

Rounding and the gross-up formula are the same as in Installment Options: Pricing guide.

Full coverage on direct-collection terminals too

If your terminal operates in direct-collection (direct) mode, this endpoint still returns every card profile applicable to you; brand groups are built for every brand configured on your terminal’s underlying connection (not only the ones in your terminal’s own installment program), because direct-collection rates come from a different source. The single-payment (cash) row is produced only if your terminal supports single payment (1 is in your effective installment set), exactly as in pool mode; installment rows are added only where that brand has installment permission at your terminal. The coverage guarantee applies here too.

Rate limit

This endpoint shares the same rate limit bucket as Installment Options — the per-minute ceiling per partner is common to both endpoints. If exceeded, you get rate_limited (429); this endpoint’s response also carries no Retry-After header.

Possible errors

Code	HTTP	Reason
validation_error	400	terminalId is blank/missing · baseAmount < 1 · customerCommissionShareBps is out of range or was sent without baseAmount.
terminal_not_allowed	403	The terminal does not belong to you or is inactive.
commission_share_not_applicable	422	Your terminal’s commission basis is net and you sent a partial customerCommissionShareBps — a net basis passes the commission through in full by definition; omitting the field or sending 10000 is accepted.
rate_limited	429	Too many requests: the rate limit was exceeded.

Full list: Error Codes.

Related

• Installment Options — the authoritative installment × rate lookup once you have the card’s BIN.
• Create Payment — you send the installment count and final amount when creating a payment.