Donations

VINR supports charitable donation flows alongside regular payments. You can offer customers fixed preset amounts to choose from, an open free-form entry field, or a round-up-to-donate prompt at checkout. Under the hood every donation is a standard payment with a donation flag set — that flag changes receipt language, adds a charity line to the settlement record, and adjusts the reporting category so donation totals stay separate from your trading revenue.

Preset and free-form amountsAskCopy

Use a Checkout session when you want VINR to host the donation UI. Pass donationType: 'preset' and an amounts array to render a set of selectable buttons; pass donationType: 'open' to render a text field where the donor enters any amount.

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

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

const session = await vinr.checkout.sessions.create({
  currency: 'GBP',
  description: 'Donate to the VINR Community Fund',
  returnUrl: 'https://yoursite.com/donate/thanks',
  donation: {
    type: 'preset',
    amounts: [500, 1000, 2500],
    charityName: 'VINR Community Fund',
    charityRegNumber: 'GB-CHY-123456',
    taxDeductible: true,
  },
  metadata: { campaign: 'spring-2026' },
});

// session.url → "https://checkout.vinr.com/c/cs_..."
// Hosted checkout renders three buttons: £5 · £10 · £25

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

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

const session = await vinr.checkout.sessions.create({
  currency: 'GBP',
  description: 'Donate any amount to the VINR Community Fund',
  returnUrl: 'https://yoursite.com/donate/thanks',
  donation: {
    type: 'open',
    charityName: 'VINR Community Fund',
    charityRegNumber: 'GB-CHY-123456',
    taxDeductible: true,
  },
  metadata: { campaign: 'spring-2026' },
});

// session.url → "https://checkout.vinr.com/c/cs_..."
// Hosted checkout renders a free-text amount field

When a donor completes the session VINR creates a pay_… object on your behalf. The donation sub-object on that payment is set automatically from the session configuration — you do not need to set it again on the resulting payment.

Round-up donationsAskCopy

Round-up donations let a customer top their order total up to the nearest whole currency unit and give the difference to charity. Pass donation: { type: 'roundUp' } on any payment creation request. VINR calculates the round-up at checkout, presents it to the customer as an opt-in, and — if accepted — charges the rounded total. The donationAmount field on the completed payment tells you how much was donated.

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

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

const payment = await vinr.payments.create({
  amount: 1870,
  currency: 'EUR',
  description: 'Order #3041',
  returnUrl: 'https://yoursite.com/orders/3041/complete',
  donation: {
    type: 'roundUp',
    charityName: 'VINR Community Fund',
    charityRegNumber: 'EU-CHY-789012',
    taxDeductible: false,
  },
  metadata: { orderId: '3041' },
});

// After customer accepts the round-up at checkout:
// payment.amount         → 1870   (original order amount)
// payment.donationAmount → 130    (€1.30 rounded up to €20.00)
// payment.totalAmount    → 2000   (total charged to the card)

If the customer declines the round-up prompt, donationAmount is 0 and totalAmount equals the original amount.

Receipts and taxAskCopy

When donation is present on a payment, VINR automatically switches the receipt to charitable language — the subject line, body copy, and footer reference the charity name rather than your trading name. For jurisdictions that require a formal acknowledgement of a tax-deductible gift, set donation.taxDeductible: true. VINR then formats the receipt to meet the jurisdictional requirements on file for your account (e.g. Gift Aid statements in the UK, substantiation notices in the US under IRC § 170).

Donation config fieldsAskCopy

ReportingAskCopy

Donations appear as a separate line in your settlement under category: 'donation', keeping them distinct from trading revenue. Use the reporting API to pull donation totals over any period by filtering balance transactions on that category.

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

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

const transactions = await vinr.balanceTransactions.list({
  category: 'donation',
  created: {
    gte: '2026-05-01T00:00:00Z',
    lte: '2026-05-31T23:59:59Z',
  },
  limit: 100,
});

const totalDonated = transactions.data.reduce(
  (sum, tx) => sum + tx.amount,
  0,
);

// totalDonated → sum of all donation amounts in minor units for the period

Each balance transaction in the result links back to the originating pay_… object via tx.sourceId. Export these records in CSV or JSON from the Dashboard under Reporting → Transactions → filter: Donations for offline reconciliation. See Reconciliation for the full settlement model.

Next stepsAskCopy