Reporting & exports

Reports turn the raw stream of payments, invoices, payouts, and loyalty events into the summaries your finance and operations teams actually work from — reconciliation files, revenue rollups, and audit trails. VINR generates reports asynchronously: you request one, VINR builds it, and you download a signed file or stream rows over the API.

Available reportsAskCopy

Each report type covers one domain and accepts a date range plus optional filters. All amounts are integers in minor units (1000 = EUR 10.00) and respect the currency on each underlying object.

Generating a reportAskCopy

A report run is created against a type and an interval, then resolves from pending to succeeded (or failed). Poll the run or subscribe to the report.completed event rather than blocking.

import { Vinr } from '@vinr/sdk';
const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

// Request a payments report for April 2026.
const run = await vinr.reports.create({
  type: 'payments',
  interval: { start: '2026-04-01', end: '2026-04-30' },
  columns: ['id', 'created', 'status', 'amount', 'fee', 'net', 'currency'],
  format: 'csv',                  // or 'json'
});

// run.status === 'pending' — wait for completion, then fetch the file URL.
const ready = await vinr.reports.waitUntilDone(run.id);
console.log(ready.fileUrl);       // signed, expires in 1 hour

The same call over raw REST:

curl https://api.vinr.com/v1/reports \
  -H "X-Api-Key: $VINR_SECRET_KEY" \
  -d type=payments \
  -d interval[start]=2026-04-01 \
  -d interval[end]=2026-04-30 \
  -d format=csv

Scheduling exportsAskCopy

For recurring delivery, attach a schedule to a report definition instead of calling create from a cron of your own. VINR runs it on the cadence you set and can push the result to a destination.

const schedule = await vinr.reports.schedules.create({
  type: 'balance_transactions',
  frequency: 'daily',
  format: 'csv',
  delivery: { type: 'sftp', destination: 'finance-recon' },
});

Report schemasAskCopy

The columns you request map to typed fields. For the payments report the core schema is:

Omitting columns returns the full default schema for the type. Requesting a column that doesn't exist for a type fails the run with a report.invalid_column error.

API access to reportsAskCopy

Beyond file exports, list and inspect runs programmatically — useful for building an internal reporting dashboard or verifying that a scheduled run actually fired.

// Did last night's reconciliation report succeed?
const runs = await vinr.reports.list({
  type: 'balance_transactions',
  status: 'succeeded',
  limit: 1,
});

for await (const row of vinr.reports.rows(runs.data[0].id)) {
  // Stream JSON rows without downloading the whole file.
  ledger.append(row);
}

Financial reportsAskCopy

Financial reports are the authoritative source for reconciling VINR activity against your general ledger. Each covers one settlement period and is immutable once generated.

Settlement reconciliation

The settlement reconciliation report ties every captured payment to the net amount that landed in your bank account after fees, refunds, and adjustments. It is the primary tool for closing your books each period.

Two granularities are available:

const run = await vinr.reports.create({
  type: 'balance_transactions',
  interval: { start: '2026-05-01', end: '2026-05-31' },
  granularity: 'transaction',   // or 'batch'
  format: 'csv',
});

Each row includes: payment id, capture date, gross amount, processing fee, interchange fee, scheme fee, net amount, settlement batch id, and payout id — enough to reconcile from gross revenue to the bank deposit line.

Invoice reconciliation

The invoice reconciliation report (type invoices) matches every finalized invoice to the payments that settled it — including partial payments, overpayments, and credit note applications. Finance teams use it to close accounts receivable.

const run = await vinr.reports.create({
  type: 'invoices',
  interval: { start: '2026-05-01', end: '2026-05-31' },
  columns: ['id', 'number', 'customer', 'amountDue', 'amountPaid', 'tax', 'status'],
  format: 'csv',
});

The payment_accounting variant of this report is formatted for direct import into common accounting systems (QuickBooks, Xero, NetSuite) — contact support to enable it for your account.

Operational reportsAskCopy

Operational reports cover specific transaction types and authentication events, useful for debugging, compliance, and product analytics.

3D Secure authentication report

The 3DS authentication report gives a per-transaction view of authentication outcomes — authentication result, ECI code, exemption type applied, and challenge outcome. Use it to measure your SCA challenge rate and tune the Authenticate module.

const run = await vinr.reports.create({
  type: '3ds_authentication',
  interval: { start: '2026-05-01', end: '2026-05-31' },
  columns: ['paymentId', 'authResult', 'eci', 'exemption', 'challengeOutcome'],
  format: 'csv',
});

The conversion report (type 3ds_conversion) aggregates by BIN and shows authentication-to-capture conversion rates — the key metric for identifying issuers that over-challenge.

Balance transfers report

Covers all internal transfers in a period: source account, destination account, amount, currency, status, and reason. Use it to audit platform fund flows or reconcile sub-merchant balances.

const run = await vinr.reports.create({
  type: 'balance_transfers',
  interval: { start: '2026-05-01', end: '2026-05-31' },
  format: 'csv',
});

Dynamic Currency Conversion report

If DCC is enabled, the DCC report shows each transaction where a conversion was offered, whether the cardholder accepted, the original and presented currencies, and the exchange rate applied. Required for scheme compliance reporting.

const run = await vinr.reports.create({
  type: 'dcc_transactions',
  interval: { start: '2026-05-01', end: '2026-05-31' },
  format: 'csv',
});

Received payment details

The received payments report covers all authorizations received in the window, including declined and voided transactions — not just captured payments. Useful for authorization rate analysis and debugging soft-decline patterns.

const run = await vinr.reports.create({
  type: 'received_payments',
  interval: { start: '2026-05-01', end: '2026-05-31' },
  columns: ['id', 'created', 'authCode', 'status', 'failureCode', 'amount', 'currency'],
  format: 'csv',
});

Closing your fiscal periodAskCopy

At month-end, the recommended close sequence is:

// List payouts that settled in May
const payouts = await vinr.payouts.list({
  arrivalDate: { gte: '2026-05-01', lte: '2026-05-31' },
  status: 'paid',
});

// For each payout, fetch its balance transaction breakdown
for (const payout of payouts.data) {
  const txns = await vinr.balanceTransactions.list({ payout: payout.id });
  const net = txns.data.reduce((s, t) => s + t.net, 0);
  console.assert(net === payout.amount, `Mismatch on ${payout.id}`);
}

Next stepsAskCopy