# Installments

> Let customers split a purchase into equal monthly payments at the terminal.

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 works

**You create a terminal payment with installments enabled**

Pass `installments: { enabled: true }` on the payment create call. No plan details are needed — the terminal discovers available plans from the issuer after the card is read.

**Customer presents their card**

The terminal reads the card and queries the issuer for available installment plans. This adds approximately 1–2 seconds to the card interaction.

**Installment plan selection screen**

If the issuer returns available plans, the terminal displays them. The customer selects a plan (e.g. "3 months at $15.00/month") or chooses to pay in full. Plans are displayed in the cardholder's currency if DCC is also active.

**Authorisation and settlement**

VINR authorises and settles the full purchase amount in your next settlement run. The installment schedule is between the cardholder and their issuer — you receive the full amount upfront.

## Enable installments

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 config

```typescript
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 response

```typescript
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`.

## Eligibility

| Condition            | Requirement                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------ |
| Card scheme          | Visa and Mastercard only                                                                               |
| Issuer participation | The cardholder's issuer must support instalment programmes                                             |
| Transaction amount   | Above the minimum configured on your account                                                           |
| Market               | Available in markets where Visa Instalments or Mastercard Instalment are supported (varies by country) |
| Account              | Installments must be enabled at account level                                                          |

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

## Combining with DCC

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 tipping

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 transactions

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 steps

[Dynamic Currency Conversion](/docs/payments/in-person/dcc) — Installments and DCC can be combined — plans display in the cardholder's home currency.

[In-person refunds](/docs/payments/in-person/refunds) — Issue full or partial refunds on installment transactions.

[All features](/docs/payments/in-person/features) — Overview of all optional terminal features.