SDKs & libraries

Official VINR server, client, and mobile SDKs.

View as MarkdownInstall skills

VINR maintains official SDKs across server, browser, and mobile runtimes. Every SDK is generated from the same VINR OpenAPI spec and versioned against the API, so a method that exists in the Node SDK behaves identically in Python, Go, or Swift. This page covers what each SDK is for, how to install it, and the support guarantees behind them.

Server SDKsAsk

Server SDKs hold your secret key and call the full API surface — Payments, Billing, and Engagement. They are the only place you should ever use a VINR_SECRET_KEY. Each handles retries with idempotency keys, request signing, pagination, and webhook verification for you.

LanguagePackageMin runtimeRepository
Node / TypeScript@vinr/sdkNode 18+github.com/vinr/vinr-node
PythonvinrPython 3.9+github.com/vinr/vinr-python
Gogithub.com/vinr/vinr-goGo 1.21+github.com/vinr/vinr-go
RubyvinrRuby 3.1+github.com/vinr/vinr-ruby
PHPvinr/vinr-phpPHP 8.1+github.com/vinr/vinr-php
Javacom.vinr:vinr-javaJava 11+github.com/vinr/vinr-java
import { Vinr } from '@vinr/sdk';

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

const payment = await vinr.payments.create({
  amount: 1000, // EUR 10.00 in minor units
  currency: 'EUR',
  description: 'Order #1234',
});
from vinr import Vinr

vinr = Vinr(secret_key=os.environ["VINR_SECRET_KEY"])

payment = vinr.payments.create(
    amount=1000,  # EUR 10.00 in minor units
    currency="EUR",
    description="Order #1234",
)
client := vinr.New(os.Getenv("VINR_SECRET_KEY"))

payment, err := client.Payments.Create(ctx, &vinr.PaymentParams{
    Amount:      1000, // EUR 10.00 in minor units
    Currency:    "EUR",
    Description: vinr.String("Order #1234"),
})
$vinr = new Vinr\Client(getenv('VINR_SECRET_KEY'));

$payment = $vinr->payments->create([
    'amount'      => 1000, // EUR 10.00 in minor units
    'currency'    => 'EUR',
    'description' => 'Order #1234',
]);

Never ship a secret key to a browser, mobile binary, or any client device. Secret keys grant full account access. If one is exposed, roll it immediately in Settings → API Keys.

Client SDK (JavaScript)Ask

@vinr/js runs in the browser and uses your public key only. It mounts the hosted checkout, collects card and bank details inside an isolated iframe (so raw PAN data never touches your DOM and stays out of PCI scope), and confirms 3D Secure challenges.

import { VinrCheckout } from '@vinr/js';

const checkout = VinrCheckout(process.env.NEXT_PUBLIC_VINR_PUBLIC_KEY!);

// clientSecret comes from a server-side vinr.payments.create() call
const element = checkout.mount('#payment-element', {
  clientSecret: payment.clientSecret,
});

element.on('completed', ({ paymentId }) => {
  window.location.href = `/order/complete?payment=${paymentId}`;
});

The public key is safe to embed in client bundles — it can tokenize and confirm payments but cannot read customers, issue refunds, or move money.

Mobile SDKsAsk

Native mobile SDKs wrap the same public-key checkout flow with platform-native UI and Apple Pay / Google Pay support.

PlatformPackageDistribution
iOSVinriOSSwift Package Manager, CocoaPods
Androidcom.vinr:vinr-androidMaven Central
React Native@vinr/react-nativenpm
import VinriOS

let vinr = Vinr(publishableKey: "pk_live_...")

vinr.presentPaymentSheet(clientSecret: clientSecret) { result in
    switch result {
    case .completed(let paymentId): handleSuccess(paymentId)
    case .canceled:                 dismiss()
    case .failed(let error):        show(error)
    }
}
val vinr = Vinr(context, publishableKey = "pk_live_...")

vinr.presentPaymentSheet(clientSecret) { result ->
    when (result) {
        is PaymentResult.Completed -> handleSuccess(result.paymentId)
        is PaymentResult.Canceled  -> dismiss()
        is PaymentResult.Failed    -> show(result.error)
    }
}
import { useVinr } from '@vinr/react-native';

const { presentPaymentSheet } = useVinr();

const { paymentId, error } = await presentPaymentSheet({ clientSecret });
if (error) return showError(error);
handleSuccess(paymentId);

InstallationAsk

Install the package

# Node / TypeScript
npm install @vinr/sdk

# Python
pip install vinr

# Go
go get github.com/vinr/vinr-go

# PHP
composer require vinr/vinr-php

Set your environment variables

Keep keys out of source control. Sandbox keys are prefixed sk_test_ / pk_test_; live keys use sk_live_ / pk_live_.

VINR_SECRET_KEY=sk_test_...
NEXT_PUBLIC_VINR_PUBLIC_KEY=pk_test_...

Initialize and verify

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

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

// A read against the sandbox confirms keys and connectivity
const { data } = await vinr.payments.list({ limit: 1 });
console.log('Connected to VINR, payments visible:', data.length);

Test against sandbox cards before going live: 4242 4242 4242 4242 succeeds, 4000 0000 0000 0002 is declined, and 4000 0000 0000 3220 triggers a 3D Secure challenge.

Versioning & support policyAsk

SDK releases follow semantic versioning. The SDK major version tracks the pinned VINR API version it ships against; minor and patch releases are always backward compatible within a major.

Prop

Type

  • Active support — the current and previous major versions receive features, fixes, and security patches.
  • Maintenance — older majors receive security patches for 12 months after a new major ships.
  • Deprecation — removals are announced at least 90 days ahead in the changelog and surfaced as runtime warnings before they take effect.

Pin an exact SDK version in production (@vinr/sdk@4.2.1, not ^4) and upgrade deliberately. The SDK sends its version to the API, which lets VINR support reproduce issues against the exact code you run.

Next stepsAsk

Was this page helpful?
Edit on GitHub

Last updated on

On this page