Flexible instalments
VINR-managed instalment plans — define the schedule and let VINR collect each payment automatically.
Flexible instalments are VINR-managed payment plans where you define the schedule — number of instalments, amounts, and due dates — and VINR charges the customer's saved payment method on each due date automatically. Unlike Mastercard Installments, which are managed by the issuing bank, flexible instalments give you full control over the plan structure and surfacing.
How it worksAsk
- The customer selects a plan at checkout (for example, "Pay in 3 monthly instalments of €150").
- VINR collects and saves the customer's payment method.
- The first instalment is charged immediately.
- VINR charges subsequent instalments automatically on the dates you specify.
- You receive a webhook event for each instalment —
instalment.chargedon success orinstalment.failedon failure.
Creating an instalment planAsk
Create an instalment plan when the customer confirms checkout. Provide the total amount, currency, and a schedule of individual charges:
import { Vinr } from '@vinr/sdk';
const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });
// TODO: confirm SDK resource name with engineering — may be vinr.installmentPlans (US spelling)
const plan = await vinr.instalmentPlans.create({
customer: 'cus_ABC123',
paymentMethod: 'pm_XYZ789',
description: 'Order #3301 — 3-month plan',
currency: 'EUR',
instalments: [
{ amount: 15000, dueDate: '2026-06-04' }, // first — charged immediately
{ amount: 15000, dueDate: '2026-07-04' },
{ amount: 15000, dueDate: '2026-08-04' },
],
metadata: { orderId: '3301' },
});
// plan.id → "ip_ABC..."
// plan.status → "active"Amounts are in minor units — 15000 is €150.00. All instalments in a plan must use the same currency.
Webhook eventsAsk
VINR fires events for each instalment lifecycle change:
| Event | When it fires |
|---|---|
instalment.charged | An instalment was successfully charged |
instalment.failed | An instalment charge failed (insufficient funds, expired card, etc.) |
instalment.plan.completed | All instalments in the plan were successfully collected |
instalment.plan.cancelled | The plan was cancelled before completion |
// POST /webhooks/vinr
const event = vinr.webhooks.verify(rawBody, req.headers['x-vinr-signature']);
if (event.type === 'instalment.charged') {
const instalment = event.data;
console.log(`Instalment ${instalment.sequence} of ${instalment.plan.total} charged — ${instalment.amount / 100} EUR`);
}
if (event.type === 'instalment.failed') {
// Notify the customer and allow them to update their payment method
}Retry logicAsk
When an instalment charge fails, VINR retries on a configurable schedule (default: 3 attempts over 7 days). If all retries fail, the instalment enters a failed state and instalment.failed fires with final: true. At that point, you can prompt the customer to update their payment method and manually retry:
// TODO: confirm exact method name with engineering — retrying an individual
// instalment may be vinr.instalmentPlans.retryInstalment() or similar
await vinr.instalmentPlans.retry('ip_ABC123', {
instalmentId: 'inst_ABC123',
paymentMethod: 'pm_NEW456', // optional — use a different payment method
});CancellationAsk
Cancel an active instalment plan at any time. Cancellation stops future charges; any already-collected instalments are not refunded automatically. Issue refunds separately if required.
await vinr.instalmentPlans.cancel('ip_ABC123', {
reason: 'requested_by_customer',
});Early repaymentAsk
To let a customer pay off the remaining balance early, charge the outstanding amount in a single payment and then cancel the plan:
const plan = await vinr.instalmentPlans.retrieve('ip_ABC123');
// Sum the remaining instalment amounts
const remaining = plan.instalments
.filter(i => i.status === 'pending')
.reduce((sum, i) => sum + i.amount, 0);
await vinr.payments.create({
amount: remaining,
currency: plan.currency,
customer: plan.customer,
paymentMethod: plan.paymentMethod,
description: `Early repayment — ${plan.description}`,
});
await vinr.instalmentPlans.cancel('ip_ABC123', { reason: 'early_repayment' });See alsoAsk
Mastercard Installments
Issuer-managed instalment plans via Mastercard.
Manage payment methods
Save and update payment methods for instalment charges.
Instalments overview
Compare both instalment models.
Last updated on
