Installments

Installment payments let customers split a single purchase into equal monthly payments at the point of sale. VINR handles the installment plan negotiation between the terminal, the card scheme, and the issuer — your integration sends a single payments.create call and receives the full purchase amount in your next settlement run, regardless of what payment schedule the customer selects.

How it worksAskCopy

Enable installmentsAskCopy

Installments must be enabled at account level:

1. Go to Dashboard → Settings → Payment processing → Installments.
2. Toggle Enable installments on.
3. Optionally set a minimum transaction amount (recommended: at least $50 / €50 equivalent).

API: pass installment configAskCopy

import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const terminalPayment = await vinr.terminal.payments.create({
  terminalId: 'term_01HZ5QXYZ',
  amount: 60000,
  currency: 'EUR',
  reference: 'order_3310',
  installments: {
    enabled: true,
  },
});

Reading installment details on the responseAskCopy

const completed = event.data.object;

if (completed.installmentPlan) {
  console.log(completed.installmentPlan.count);          // 6
  console.log(completed.installmentPlan.monthlyAmount);  // 10000 (cents)
  console.log(completed.installmentPlan.totalAmount);    // 60000 (cents)
  console.log(completed.installmentPlan.issuerPlanId);   // issuer reference
}

// You settle the full amount regardless of the plan
console.log(completed.amountCaptured); // 60000

If the customer paid in full (no plan selected) or the card was not eligible, completed.installmentPlan is null.

EligibilityAskCopy

American Express, Discover, and UnionPay cards are not eligible. The terminal shows no plan screen for ineligible cards — payment proceeds normally.

Combining with DCCAskCopy

When both DCC and installments are active and the customer selects DCC:

1. The DCC exchange rate is applied first.
2. The installment plan screen shows plans in the cardholder's home currency.
3. The monthly amount displayed is the DCC-converted amount divided by the number of installments.

You still settle the full amount in your local currency.

Combining with tippingAskCopy

Installments and tipping can coexist. The tip is added to the base amount before installment plans are calculated, so the monthly amounts shown to the customer include the tip.

Refunds on instalment transactionsAskCopy

Refunds on installment transactions are processed via vinr.refunds.create in the same way as any other card-present refund. VINR credits the full refund amount to the cardholder. The installment plan is cancelled on the issuer side — the cardholder no longer owes remaining instalments. For partial refunds, the remaining instalments are adjusted proportionally by the issuer.

Next stepsAskCopy