Multicurrency & FX

VINR can show a customer a price in their own currency, process the charge in that currency, and settle the proceeds into yours — converting at a single, transparent rate locked at processing time. This page explains the three currencies involved, how rates and markup are applied, and how to choose your settlement currency.

The three currenciesAskCopy

Every cross-currency payment touches up to three distinct currencies. Keeping them separate is the key to reasoning about FX.

Presentment and processing are usually the same — the customer pays in their currency. The conversion happens between the processing currency and your settlement currency, applied when the payment is captured.

customer pays ¥1,500 (presentment = processing)
        │
        ▼  FX at capture time
   settles as €9.12 (settlement) → your EUR balance

Presenting prices in local currencyAskCopy

To charge in a currency, set it on the payment. Amounts remain integers in that currency's minor units, and zero-decimal currencies like JPY use the whole number.

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

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

const payment = await vinr.payments.create({
  amount: 1500,            // ¥1,500 — JPY is zero-decimal, no minor units
  currency: 'JPY',         // presentment & processing currency
  description: 'Order #4821',
  returnUrl: 'https://yoursite.com/payment/complete',
  metadata: { orderId: '4821' },
});

To pick the right presentment currency, read the customer's country or locale from your storefront, or call the rates endpoint to display a live converted price before checkout (see below).

Supported currenciesAskCopy

VINR processes 135+ currencies. Settlement is supported into a smaller set tied to your payout bank accounts. A few representative groups:

FX rates & markupAskCopy

When a payment is captured in a currency different from its settlement currency, VINR applies a conversion rate composed of two parts:

The rate is locked at capture time, not at payment creation, so the amount that reaches your balance is deterministic once funds are captured. Both the mid-market rate and the applied rate are recorded on the payment's fxDetails for reconciliation.

const payment = await vinr.payments.retrieve('pay_3Nf8x2a');

// payment.fxDetails → {
//   processingCurrency: 'JPY',
//   settlementCurrency: 'EUR',
//   midMarketRate: 0.006120,
//   markup: 0.01,
//   appliedRate: 0.006059,
//   settledAmount: 909,        // €9.09 in minor units
// }

To show a customer a converted price before they pay, fetch an indicative rate. This rate is for display only — the binding rate is the one locked at capture.

curl https://api.vinr.com/v1/fx/rates?from=EUR&to=JPY \
  -H "X-Api-Key: $VINR_SECRET_KEY"

{
  "from": "EUR",
  "to": "JPY",
  "midMarketRate": 163.40,
  "markup": 0.01,
  "appliedRate": 161.79,
  "asOf": "2026-05-30T09:00:00Z"
}

Settlement currency selectionAskCopy

Your default settlement currency is set during onboarding and matches your primary payout bank account. You have two ways to influence where money lands:

const payment = await vinr.payments.create({
  amount: 5000,                  // $50.00
  currency: 'USD',
  settlementCurrency: 'USD',     // settle as USD, skip conversion to EUR
  returnUrl: 'https://yoursite.com/payment/complete',
});

Settling in the same currency you process avoids FX markup entirely — useful if you have local bank accounts in your major markets. When no same-currency account exists, VINR converts to your default at the applied rate above.

Reconciliation & reportingAskCopy

Each cross-currency payment carries its full fxDetails, and payouts group settled amounts by settlement currency. The payment.completed webhook includes the settled amount and applied rate, so you can post the exact figure to your ledger without re-deriving it.

See Reconciliation for matching settled amounts to bank deposits.

Next stepsAskCopy