Dynamic Currency Conversion

Dynamic Currency Conversion (DCC) detects when a customer presents a foreign-issued card and offers to complete the transaction in the cardholder's home currency rather than your local settlement currency. The customer sees the exact amount they will be charged in their own currency — including the exchange rate and any DCC margin — and chooses which currency to pay in.

Regardless of the customer's choice, you always settle in your local currency. The exchange-rate risk and DCC margin are passed to the cardholder and the DCC provider — not to you.

RequirementsAskCopy

• DCC must be enabled at account level (Dashboard → Settings → Payment processing → Dynamic Currency Conversion).
• A DCC agreement with VINR is required. Contact your account manager to activate DCC for your account.
• DCC is subject to Visa and Mastercard programme rules and is not available in all markets.

No code change is required once DCC is enabled — the terminal handles detection and the offer flow automatically.

How it works at the terminalAskCopy

Reading DCC on the responseAskCopy

const completed = event.data.object;

if (completed.dcc) {
  console.log(completed.dcc.cardholderCurrency);   // "EUR"
  console.log(completed.dcc.cardholderAmount);      // 4123 (cents in EUR)
  console.log(completed.dcc.exchangeRate);          // 1.0961
  console.log(completed.dcc.margin);                // 0.03 (3% DCC margin)
  console.log(completed.dcc.accepted);              // true — customer chose DCC
}

// Your settlement amount is always in your local currency
console.log(completed.amountCaptured); // 4500 (cents in USD)
console.log(completed.currency);       // "USD"

If the customer declined DCC or the card was not eligible, completed.dcc is null.

DCC eligibilityAskCopy

DCC is offered when all of the following conditions are met:

• The card BIN is identified as a foreign-issued card (i.e. issued in a different country than your terminal's assigned location).
• The cardholder's home currency differs from your settlement currency.
• The card scheme (Visa or Mastercard) supports DCC for this currency pair.
• The transaction amount exceeds the minimum DCC threshold (typically equivalent to ~$10 USD — set by your DCC agreement).
• DCC is enabled on the terminal's assigned location.

American Express, Discover, and UnionPay cards are not eligible for DCC on VINR terminals.

Suppress DCC for a specific transactionAskCopy

To prevent DCC from being offered on a single payment (for example, if your POS system manages currency conversion itself):

const terminalPayment = await vinr.terminal.payments.create({
  terminalId: 'term_01HZ5QXYZ',
  amount: 4500,
  currency: 'USD',
  reference: 'order_5509',
  dccConfig: {
    enabled: false,
  },
});

ReportingAskCopy

DCC transactions appear in Dashboard → Payments with a DCC badge. The report export includes columns for cardholder currency, cardholder amount, exchange rate, and DCC margin for reconciliation against your DCC provider statement.

Next stepsAskCopy