Installments

Installments (taksit) are available on credit cards only. Debit and prepaid cards are always charged in one payment. The platform works out which installment counts a given card can pay at your business and who bears the cost, so ask it before you show the choices to a customer.

Why not every card can pay in installments

In Turkey installments run on card programs such as Bonus, World, Axess, Maximum, Paraf and Bankkart. A program belongs to one owner bank, and other banks may join it so that their credit cards carry the same program. An installment payment succeeds only when all of these hold:

• your price list defines a price for that installment count, and your account is allowed to offer it;
• at least one acquiring terminal can run that count for the card. A terminal runs installments when the card is issued by the terminal's own bank or when the card's program is one the terminal's bank supports.

The result differs card by card, which is why you ask for a preview with the card's BIN (first 6 to 8 digits) rather than offering a fixed list.

Preview the options

POST /v1/installment_plans/preview accepts a publishable key, so you can call it straight from the checkout page as the customer types the first digits of the card, or from your server with a secret key. Never send a full card number to it.

{
  "bin": "435508",
  "amount": 100000,
  "currency": "try"
}

curl -X POST https://pay.example.com/v1/installment_plans/preview \
  -H "Authorization: Bearer pk_sandbox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bin": "435508", "amount": 100000, "currency": "try"}'

For a saved card send "payment_method": "pm_…" instead of bin.

{
  "object": "installment_preview",
  "card": {
    "brand": "visa",
    "card_type": "credit",
    "program": "axess",
    "programs": ["axess"],
    "issuer_bank_code": "0046",
    "domestic": true
  },
  "installment_surcharge_mode": "customer_pays",
  "plans": [
    {"count": 1, "amount": 100000, "surcharge": 0, "amount_charged": 100000, "per_installment": 100000, "first_installment": 100000},
    {"count": 3, "amount": 100000, "surcharge": 3500, "amount_charged": 103500, "per_installment": 34500, "first_installment": 34500},
    {"count": 6, "amount": 100000, "surcharge": 6900, "amount_charged": 106900, "per_installment": 35633, "first_installment": 35635}
  ]
}

plans lists only the counts this card can really pay with you; count 1 is listed whenever any terminal can take the card. A debit card, or a foreign card, typically gets count 1 only.

Who pays: installment_surcharge_mode

• merchant_absorbs: the customer pays the base amount in n parts; the cost is yours. surcharge is 0.
• customer_pays: a surcharge is added for that count. The card is charged amount_charged = amount + surcharge.

Amounts in each plan are integers in minor units:

Show the customer amount_charged and the per-installment amount.

Pay in installments

Send the chosen count when you create or confirm the payment. Keep amount as the base amount; the platform adds the surcharge.

{
  "amount": 100000,
  "currency": "try",
  "confirm": true,
  "payment_method_data": {
    "type": "card",
    "card": {
      "number": "4355080000000013",
      "exp_month": 12,
      "exp_year": 2030,
      "cvc": "123",
      "holder_name": "Test Customer"
    },
    "billing_details": {
      "name": "Test Customer",
      "address": {"line1": "Bagdat Caddesi 1", "city": "Kadikoy", "country": "TR"}
    }
  },
  "payment_method_options": {"card": {"installments": {"count": 3}}},
  "return_url": "https://shop.example.com/pay/return"
}

The payment then shows installments: 3, amount: 100000 (base), surcharge: 3500 and amount_charged: 103500. Later references to the sale use the base amount: amount_received and refunds (POST /v1/refunds) are in base units. A refund of the whole base amount also returns the proportional surcharge to the card (amount_returned_to_card).

Errors

Always base the options you offer on a fresh preview: terminals, programs and your price list can change.