Installments

Installments let customers split a single purchase into equal monthly payments while VINR advances the full purchase amount to you immediately after the transaction settles. Credit risk on the repayment schedule stays with the card issuer or BNPL provider — not with your business. From your perspective an installment payment settles like any other card charge.

EligibilityAskCopy

Installment programs are offered by participating card issuers and BNPL networks. Availability varies by market and currency.

Offer installments at checkoutAskCopy

Pass installments: { enabled: true } when creating a payment. The VINR hosted checkout automatically presents available installment plans when the customer's card supports them. If the card does not qualify, checkout proceeds as a standard one-shot payment.

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

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

const payment = await vinr.payments.create({
  amount: 60000,                  // €600.00
  currency: 'EUR',
  description: 'VINR Pro annual kit',
  returnUrl: 'https://yoursite.com/orders/complete',
  installments: {
    enabled: true,
  },
});

// Redirect the customer to payment.checkoutUrl.
// The hosted checkout surfaces installment plans if the card is eligible.

After the customer selects a plan and authenticates, the payment moves to completed and payment.completed fires. The installments object on the completed payment reflects the plan the customer chose.

Specify a planAskCopy

To pre-select the number of installments instead of letting the customer choose, pass count alongside enabled: true. If the issuer supports the requested count it is applied automatically; otherwise VINR falls back to the closest available option and records the resolved plan on the payment object.

const payment = await vinr.payments.create({
  amount: 60000,
  currency: 'EUR',
  description: 'VINR Pro annual kit',
  returnUrl: 'https://yoursite.com/orders/complete',
  installments: {
    enabled: true,
    count: 3,
    interval: 'month',
    firstPaymentDate: '2026-06-01',
  },
});

Merchant settlementAskCopy

When a customer completes an installment payment, VINR settles the full purchase amount to your account in the next regular settlement cycle — not spread across the installment schedule. The only difference from a standard card payment is the processing fee structure: an installment fee applies in addition to the base interchange, and both are shown as separate line items on your statement.

const payment = await vinr.payments.retrieve('pay_3Nf8x2a');

console.log(payment.installments);
// {
//   enabled: true,
//   count: 3,
//   interval: 'month',
//   firstPaymentDate: '2026-06-01',
//   resolvedCount: 3,         // plan confirmed by the issuer
//   issuerProgram: 'mastercard_installments'
// }

const payment = await vinr.payments.retrieve('pay_3Nf8x2a');

console.log(payment.feeBreakdown);
// {
//   processingFee: 174,         // base interchange, minor units
//   installmentFee: 90,         // installment program surcharge
//   totalFee: 264
// }

Installment transactions appear in reconciliation with a payment_method_type of card_installment. Use this field to filter or aggregate installment volume in your reporting.

Refunds on installment paymentsAskCopy

Refunds interact with installment plans at the issuer level. VINR processes the refund on your side identically to any card refund — the adjustment to the cardholder's repayment schedule is handled by the issuer.

Full refund — Refunding the complete purchase amount cancels the outstanding installment plan with the issuer. The cardholder is no longer billed for future installments.

const refund = await vinr.refunds.create({
  payment: 'pay_3Nf8x2a',
  reason: 'requested_by_customer',
});

// refund.status → "pending"
// The issuer cancels the remaining installment schedule on confirmation.

Partial refund — A partial refund reduces the outstanding balance on the installment plan. The issuer recalculates the remaining installment amounts and notifies the cardholder. You cannot partially refund below the amount already collected in prior installments.

const partial = await vinr.refunds.create({
  payment: 'pay_3Nf8x2a',
  amount: 20000,              // €200.00 of a €600.00 installment payment
  reason: 'product_not_received',
});

For full refund mechanics, status states, and failure handling see Refunds.

Next stepsAskCopy