3D Secure

3D Secure 2 (3DS2) is the network protocol that carries Strong Customer Authentication. When a payment requires SCA, VINR drives a 3DS2 exchange with the issuer that collects device data, optionally shows a challenge, and returns a cryptographic proof of authentication. This page covers the three integration modes and how to supply or read authentication data. For the regulatory context — which payments need SCA and which exemptions apply — see Strong Customer Authentication.

Integration modesAskCopy

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

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

const payment = await vinr.payments.create({
  amount: 7900,
  currency: 'EUR',
  description: 'Order #8821',
  returnUrl: 'https://yoursite.com/orders/8821/complete',
});

// Send the customer here. VINR runs 3DS and redirects back.
console.log(payment.checkoutUrl);

const payment = await vinr.payments.create({
  amount: 7900,
  currency: 'EUR',
  description: 'Order #8821',
  returnUrl: 'https://yoursite.com/orders/8821/complete',
  authentication: {
    mode: 'redirect',
  },
});

if (payment.authentication?.status === 'required') {
  const acsUrl = payment.authentication.redirectUrl;
  // Redirect the customer to acsUrl, or load it in an iframe.
}

const payment = await vinr.payments.create({
  amount: 1500,
  currency: 'EUR',
  description: 'Top-up',
  returnUrl: 'https://yoursite.com/wallet/complete',
  authentication: {
    mode: 'data_only',
    browserInfo: {
      userAgent: req.headers['user-agent'],
      colorDepth: 24,
      screenWidth: 1440,
      screenHeight: 900,
      timeZoneOffset: -120,
      javaEnabled: false,
      language: 'en-GB',
    },
  },
});

Standalone authenticationAskCopy

Authenticate a card without immediately charging it. This is useful for verifying a card before saving it to a customer's wallet, or for pre-authenticating a marketplace seller's payout method. The returned authenticationId can be attached to a later payments.create call.

const auth = await vinr.authentication.create({
  amount: 0,
  currency: 'EUR',
  paymentMethod: 'pm_4Rk9...',
  returnUrl: 'https://yoursite.com/wallet/verify-complete',
  deviceChannel: 'browser',
  challengeIndicator: 'challenge_requested',
  browserInfo: {
    userAgent: req.headers['user-agent'],
    colorDepth: 24,
    screenWidth: 1440,
    screenHeight: 900,
    timeZoneOffset: -120,
    javaEnabled: false,
    language: 'en-GB',
  },
});

// auth.authenticationId → "aut_7Kx2p..."
// auth.status           → "pending" → "authenticated" | "not_authenticated"
// auth.redirectUrl      → present if a challenge is required

// Later: attach to a payment with no re-authentication needed.
const payment = await vinr.payments.create({
  amount: 9900,
  currency: 'EUR',
  customer: 'cust_8Qd2...',
  paymentMethod: 'pm_4Rk9...',
  authenticationId: auth.authenticationId,
  confirm: true,
});

Passing 3DS dataAskCopy

Supply these fields on authentication (inside payments.create or authentication.create) to improve the issuer's risk decision and maximize frictionless results.

Reading the resultAskCopy

After authentication completes, inspect authentication.status on the payment or authentication object. The status determines who bears liability if the payment is later disputed as unauthorized.

Verify the outcome from a webhook rather than relying on the browser redirect alone:

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

switch (event.type) {
  case 'payment.completed':
    await fulfillOrder(event.data.metadata.orderId);
    break;
  case 'payment.authentication_failed':
    await notifyAuthFailed(event.data.id);
    break;
}

TestingAskCopy

The sandbox drives authentication outcomes from the card number. Use any future expiry, any 3-digit CVC, and any postal code.

To simulate a specific ECI value, pass test.eciOverride in the authentication object. This field is ignored outside the sandbox.

const payment = await vinr.payments.create({
  amount: 4900,
  currency: 'EUR',
  returnUrl: 'https://yoursite.com/complete',
  authentication: {
    test: {
      eciOverride: '06',
    },
  },
});

// authentication.eci → "06"  (attempted authentication)
// authentication.status → "attempted"

For the challenge card (4000 0000 0000 3220), approve or fail the challenge from Dashboard → Sandbox → Authentication to control the final status without browser interaction.

Next stepsAskCopy