Core concepts

Every VINR integration — whether you're taking a one-off payment or running a subscription-plus-loyalty loop — is built on the same small set of ideas. This page explains them once so the rest of the documentation makes sense.

Three products, one platformAskCopy

VINR exposes three products through a single API and a single SDK. You can use any one of them independently, or combine all three.

The three products share one customer object. A cust_ you create for a first payment is the same record you attach a subscription and a loyalty account to — no duplicate data, no re-collecting card details, no second identity for the same person.

Objects and IDsAskCopy

Every resource in VINR is an object with a typed, prefixed ID. The prefix tells you exactly what you're looking at — in logs, in dashboard URLs, and in webhook payloads.

The event modelAskCopy

VINR is event-driven. Every meaningful state change — a payment completing, an invoice generating, a customer earning points — emits an evt_ object delivered to your registered webhook endpoint. Do not poll the API for state changes; react to events instead.

A webhook payload always has the same shape:

{
  id: "evt_01j2k...",
  type: "payment.completed",
  created: 1717200000,
  data: { /* the full object that changed */ }
}

Your endpoint must verify the x-vinr-signature header before trusting the payload, then return 2xx within 30 seconds. VINR retries unacknowledged deliveries with exponential backoff for up to 72 hours.

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

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

export async function POST(req: Request) {
  const payload = await req.text();
  const signature = req.headers.get('x-vinr-signature');

  const event = vinr.webhooks.verify(payload, signature);

  switch (event.type) {
    case 'payment.completed':
      await fulfillOrder(event.data.metadata.orderId);
      break;
    case 'invoice.paid':
      await grantAccess(event.data.customerId);
      break;
    case 'loyalty.points.earned':
      await notifyCustomer(event.data.customerId, event.data.amount);
      break;
  }

  return new Response('OK', { status: 200 });
}

Make every handler idempotent: store the processed evt_ id and short-circuit duplicates. VINR may redeliver the same event on retry.

Key events by product

EnvironmentsAskCopy

Every VINR account has two isolated environments. They share nothing — not keys, not objects, not money.

The SDK switches base URL automatically based on which key you provide — a sk_test_… key can never touch the live API. If you call the REST API directly, keep the host and key in sync; a live key against the sandbox host returns 401.

AuthenticationAskCopy

VINR uses two API keys per environment:

• Secret key (sk_test_… / sk_live_…) — server-side only. Used to create payments, read customer data, and verify webhooks. Never expose this in client-side code or commit it to version control.
• Public key (pk_test_… / pk_live_…) — safe for browser use. Initializes the embedded Elements UI. It cannot make server-side API calls.

Pass the secret key via the X-Api-Key header (REST) or the SDK constructor. See Authentication for scoped keys, rotation, and key management best practices.

Next stepsAskCopy