Integration models

VINR offers three integration surfaces: Hosted Checkout, Elements, and API-only. Choosing the right one determines how much you build versus how much control you have over the payment experience. Most merchants start with Checkout and never need more.

The three modelsAskCopy

CheckoutAskCopy

VINR hosts the entire payment form. You create a session from your backend, redirect the customer to checkout.vinr.com, and verify the result when they return. VINR handles card entry, Apple Pay, Google Pay, Click-to-Pay, 3DS challenges, and all error states.

const { sessionId, checkoutUrl } = await fetch(
  `${process.env.INTENT_API_URL}/checkout/session`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': process.env.VINR_API_KEY!,
    },
    body: JSON.stringify({
      amount: 5000,
      currency: 'EUR',
      successUrl: 'https://yoursite.com/success',
      cancelUrl: 'https://yoursite.com/cancel',
    }),
  }
).then(r => r.json());

window.location.href = checkoutUrl;

const result = await fetch(
  `${process.env.INTENT_API_URL}/checkout/session/${sessionId}/result`,
  { headers: { 'X-Api-Key': process.env.VINR_API_KEY! } }
).then(r => r.json());

if (result.status === 'completed') {
  await fulfillOrder(result);
}

Read the full Checkout integration guide.

ElementsAskCopy

VINR UI components are embedded directly in your page. You own the page layout, step flow, and branding — VINR owns the sensitive fields (card number, expiry, CVC). Card data is entered in VINR-hosted iframes, encrypted in the browser, and returned as a token your backend can charge. Because raw card data never touches your JavaScript or servers, SAQ-A EP (rather than full SAQ-D) applies.

The example below shows the minimum code to mount a card element inside a React component:

import { useRef } from 'react';
import { useAsparyxSDK, useAsparyxElement, useTokenReceived } from '@vinr/elements';

export default function CardForm({ intent }: { intent: Intent }) {
  const containerRef = useRef<HTMLDivElement>(null);

  const { sdk, status } = useAsparyxSDK({
    merchantId: intent.accountId,
    publicKey: intent.publicKey,
    secureFormsUrl: 'https://elements.vinr.com',
    enabled: !!intent,
  });

  useAsparyxElement(sdk, 'full-payment', {
    container: containerRef,
    amount: intent.amount,
    currency: intent.currency,
  });

  useTokenReceived(sdk, async (data) => {
    await fetch('/api/process-payment', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        intentId: intent.id,
        paymentMethod: { card: { payload: data.payload.card.payload } },
        billingDetails: data.payload.billingDetails,
      }),
    });
  });

  return (
    <>
      <div ref={containerRef} style={{ minHeight: 550 }} />
      <button
        disabled={status !== 'ready'}
        onClick={() => sdk?.submit(intent.amount, intent.currency)}
      >
        Pay
      </button>
    </>
  );
}

Read the full Elements integration guide.

API-only (Advanced flow)AskCopy

You build the entire UI, collect card data, and tokenize it yourself before passing the payload to VINR. This gives you the highest degree of control over every pixel and interaction, but it also gives you the highest PCI scope: SAQ-D, which requires a full annual assessment and quarterly network scans. Most merchants should exhaust Checkout and Elements before reaching for this model.

API-only is the right choice when:

• You are a payment platform or marketplace that needs to route funds across multiple sub-merchants.
• You have an existing card-vault or tokenization system you want to connect to VINR.
• Your enterprise compliance team mandates end-to-end control over all payment data flows.

Read the full API-only integration guide.

Decision matrixAskCopy

Changing models laterAskCopy

You can migrate from Checkout to Elements, or from Elements to API-only, without changing your backend payment logic. The pay_... payment IDs, webhook event names, and result status values are identical across all three models. The only thing that changes is the frontend integration code and your PCI scope obligations.

Next stepsAskCopy