Integration overview

VINR exposes one API and one SDK across three products — Payments, Billing, and Engagement — but each product offers several integration depths, from a hosted page you can wire up in an afternoon to a fully API-driven flow you control end to end. This page helps you pick the right entry point for your stack, your compliance posture, and how much of the UI you want to own.

Decision guideAskCopy

Start with two questions: how much UI do you want to build, and how much cardholder data do you want to touch. Touching raw card data raises your PCI DSS scope; hosted and embedded options keep that data on VINR's infrastructure.

Payments pathsAskCopy

All three payment paths produce the same payment object and emit the same payment.completed and payment.failed events, so your fulfillment logic is portable.

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

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

const payment = await vinr.payments.create({
  amount: 1000, // €10.00 in minor units
  currency: 'EUR',
  description: 'Order #1234',
  returnUrl: 'https://yoursite.com/checkout/return',
});

return Response.redirect(payment.checkoutUrl);

const session = await vinr.payments.createSession({
  amount: 1000,
  currency: 'EUR',
});
// Pass session.clientSecret to the browser and mount Elements with it.

const payment = await vinr.payments.create({
  amount: 1000,
  currency: 'EUR',
  paymentMethod: 'pm_tokenized_from_your_client',
  confirm: true,
});

See Payments for the full method matrix and capture options.

Billing pathsAskCopy

Billing is API-first: you model prod_, price_, and sub_ objects and let VINR drive the invoice lifecycle. There is no separate "hosted" tier, but you can delegate the entire payment-collection step to a hosted checkout.

const price = await vinr.prices.create({
  productId: 'prod_starter',
  amount: 2900, // €29.00 per period
  currency: 'EUR',
  recurring: { interval: 'month' },
});

const subscription = await vinr.subscriptions.create({
  customerId: 'cust_8fa2',
  priceId: price.id,
});

const event = vinr.webhooks.verify(payload, signature);
if (event.type === 'invoice.paid') {
  await grantAccess(event.data.customerId);
}

For metered plans, report usage with vinr.usage.record(...), which creates mbu_ records. See Billing.

Engagement pathsAskCopy

Engagement (loyalty) layers onto either standalone customers or your existing Payments/Billing data. You attach a loy_ account to a cust_ and award points either manually or by reacting to payment events.

// Earn points automatically when a payment completes
const event = vinr.webhooks.verify(payload, signature);
if (event.type === 'payment.completed') {
  await vinr.loyalty.points.earn({
    programId: 'prog_default',
    customerId: event.data.customerId,
    amount: Math.floor(event.data.amount / 100), // 1 point per euro
    sourcePaymentId: event.data.id,
  });
}

This produces a ptx_ transaction and emits loyalty.points.earned. Rewards (rwd_) and redemptions (rdm_) follow the same event-driven pattern. See Engagement.

Combining productsAskCopy

The biggest reason to standardize on VINR is that one cust_ object threads through all three products. A common end-to-end flow:

Next stepsAskCopy