Cards

Cards are linked to a debit or credit account at a bank. To complete a payment online, customers enter their card information at checkout. Cards are enabled by default and are supported across all integration paths. You can manage payment methods from Dashboard → Settings → Payment methods. VINR handles the return of eligible payment methods based on factors such as the transaction's amount, currency, and payment flow.

Payment flowAskCopy

A customer initiates a card payment at checkout by entering their card information. Depending on their card network and country, they may have additional security verification steps.

A card payment moves through the following stages:

1. Format check — VINR validates that card details are correctly formatted (expiry date not in the past, card number passes a Luhn check).
2. Authentication — For many European cards, the issuing bank requires a 3D Secure challenge to satisfy Strong Customer Authentication. VINR triggers this automatically on all hosted checkout surfaces.
3. Authorization — The issuing bank reserves the funds on the cardholder's account. The payment enters authorized.
4. Capture — You claim the reserved funds. With default immediate capture, this happens in the same request; the payment moves to processing, then completed.

Cards can also act as the funding source for wallet payments. When a customer pays with Apple Pay or Google Pay, VINR receives a network token representing the underlying card. The payment_method.card object is populated as normal; the wallet field indicates the provider.

Supported card brandsAskCopy

VINR supports several card brands, from large global networks like Visa and Mastercard to regional networks like Cartes Bancaires in France. When you integrate VINR, you can accept a range of card brands without additional configuration, including:

• Visa (credit, debit, and prepaid)
• Mastercard (credit, debit, and prepaid)
• American Express
• Discover & Diners Club
• China UnionPay (CUP)
• Japan Credit Bureau (JCB)
• Maestro (debit; 3D Secure frequently required)

Some brands require additional account configuration. Contact VINR support to enable Cartes Bancaires on your account.

Card brand capabilities

¹ Cartes Bancaires supports Apple Pay. For in-store NFC payments via Cartes Bancaires, contact VINR support.

VINR processes payments in 135+ currencies. Some card networks have limitations on supported presentment currencies. Review your account's enabled currencies in the Dashboard under Settings → Payment methods.

Exclude card brands

You can restrict specific card brands using custom client-side code that reads the brand field returned as the customer types their card number, and prevents submission for excluded brands.

Geographic considerationsAskCopy

VINR provides an infrastructure that handles secure payments and complies with regional regulations. This is particularly relevant with Strong Customer Authentication (SCA) rules in Europe, where additional verification steps are typically required.

SCA and 3D Secure

Some banks, especially in regulated regions like Europe, may prompt the customer to authenticate a purchase — for example, by sending a code to enter on the bank's website. This authentication step is part of Strong Customer Authentication (SCA).

SCA, in effect as part of PSD2 regulation in Europe, requires changes to how European customers authenticate online payments. Card payments use 3D Secure (3DS) to meet these requirements.

VINR handles 3DS automatically on all hosted checkout and Payment Links surfaces. For custom integrations using the Payments API, authentication is triggered based on transaction value, issuer rules, and VINR risk signals.

Instalments

Some regions support card-issuer-managed instalment payments. For instalment plans managed directly by VINR, see Instalments.

Card brand choice

The European Union requires businesses to allow customers to choose which card brand processes their transaction, because cards in the EU may carry both a local network (such as Cartes Bancaires) and an international network (such as Visa or Mastercard). See Co-badged cards & EU compliance for how to implement this choice.

Creating a paymentAskCopy

Create a payment with an amount, currency, and return URL, then redirect the customer to the hosted checkoutUrl. The hosted page collects card details and handles 3D Secure automatically.

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

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

const payment = await vinr.payments.create({
  amount: 4500,            // €45.00 in minor units
  currency: 'EUR',
  method: 'card',
  description: 'Order #1042',
  returnUrl: 'https://yoursite.com/checkout/complete',
  metadata: { orderId: '1042' },
});

// payment.id          → "pay_3Nf8x2a..."
// payment.status      → "pending"
// payment.checkoutUrl → redirect the customer here

Confirm the final state from the webhook rather than the browser redirect, which a customer may interrupt or close:

// POST /webhooks/vinr
const event = vinr.webhooks.verify(payload, req.headers['x-vinr-signature']);

if (event.type === 'payment.completed') {
  const payment = event.data;
  await fulfillOrder(payment.metadata.orderId);
}

Settlement & timingAskCopy

• Authorized — funds reserved on the card immediately; not yet in your balance.
• Captured — funds move into your VINR balance within seconds of capture.
• Settled — funds paid out to your bank per your settlement schedule (typically T+2 to T+3 business days), net of fees.

Uncaptured authorizations expire automatically — usually within 7 days, depending on the issuer — after which the hold is released back to the cardholder.

RefundsAskCopy

Refund a captured card payment in full or in part. Refunds return funds to the original card and cannot be redirected to a different card.

const refund = await vinr.refunds.create({
  payment: 'pay_3Nf8x2a...',
  amount: 1500,            // partial refund of €15.00; omit for full refund
  reason: 'requested_by_customer',
});

If a payment is still in authorized state (not yet captured), cancel it rather than refunding — this reverses the authorization at no cost and releases the hold faster.

In this sectionAskCopy

See alsoAskCopy