Guides

Guides are goal-driven walkthroughs: start to finish, copy-paste runnable, and verified against the sandbox. Each one solves a single real task — accept a payment, meter usage, award loyalty points — without making you stitch the pieces together yourself. For the why behind a feature see the product sections; for field-level detail see the API Reference.

How guides are organizedAskCopy

Every guide follows the same shape so you always know where to look:

• Overview — a short diagram or summary of the flow and which systems talk to each other.
• Steps — numbered, server-first, with runnable @vinr/sdk snippets you can paste into a backend handler.
• Test it — sandbox cards or fixtures that exercise success and failure paths.
• Go live — the swap from sandbox to live keys plus the checks that matter in production.
• Next steps — links to the guides and concepts you'll likely reach for next.

Guides are intentionally narrow. When a topic needs deep explanation (how settlement timing works, what a dispute lifecycle looks like) the guide links out to the relevant concept page instead of repeating it.

PrerequisitesAskCopy

Before you start any guide, have the following in place:

export VINR_SECRET_KEY=sk_sandbox_...

npm install @vinr/sdk

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

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

const event = vinr.webhooks.verify(
  await req.text(),
  req.headers.get('x-vinr-signature'),
);

Browse by productAskCopy

Pick the pillar that matches what you're building. Each guide is self-contained and runnable.

Payments

Accept money, handle SCA, and reconcile the result.

Billing

Sell subscriptions, meter usage, and collect on invoices.

Engagement

Reward customers and tie loyalty to real transactions.

A guide at a glanceAskCopy

To see the pattern before you commit, here's the shape almost every guide shares — create a resource server-side with an idempotency key, then react to the authoritative webhook:

// 1. create (idempotent — safe to retry)
const payment = await vinr.payments.create(
  { amount: 2500, currency: 'EUR', metadata: { orderId: 'A-1' } },
  { idempotencyKey: 'order-A-1' },
);

// 2. fulfil on the verified event, never on the redirect
function onEvent(event) {
  if (event.type === 'payment.completed') {
    fulfill(event.data.metadata.orderId); // runs exactly once
  }
}

If you internalize that pattern, every guide on this site will feel familiar.

Next stepsAskCopy