Bank transfers

Bank transfers move money directly between accounts, with no card network in between. They settle with strong finality and low cost, which makes them ideal for high-value orders, invoices, and recurring B2B billing — at the price of being slower and asynchronous. This page covers which rails VINR supports, how the push-vs-pull flow works, how to create a transfer payment, and how settlement and refunds behave.

Availability & currenciesAskCopy

VINR exposes account-to-account rails under a single bank_transfer method, automatically selecting the right network from the currency and the customer's country.

How the flow worksAskCopy

A push transfer is inherently asynchronous: you cannot confirm funds at checkout the way you can with a card. The payment exists before the money arrives.

customer's bank → [push transfer w/ reference] → VINR virtual account → [reconcile] → your balance

Creating a paymentAskCopy

Create the payment server-side and surface the returned bank instructions to your customer.

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

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

const payment = await vinr.payments.create({
  amount: 49900,                 // €499.00 in minor units
  currency: 'EUR',
  method: 'bank_transfer',
  description: 'Invoice INV-2026-0042',
  customer: 'cust_8Hk2mPq',
  metadata: { invoiceId: 'inv_8Hk2mPq' },
});

// payment.id     → "pay_3Nf8x2a..."
// payment.status → "pending"
// payment.bankTransfer → {
//   iban: "DE89 3704 0044 0532 0130 00",
//   reference: "VINR-9KX2-7QP4",   // customer MUST include this
//   accountHolder: "VINR Payments",
//   rail: "sepa_credit_transfer"
// }

Display payment.bankTransfer.reference prominently — it is how VINR attributes the inbound funds. Transfers missing or mismatching the reference land in a manual review queue and settle late.

For pull rails, collect a mandate first and reference it on the charge:

const payment = await vinr.payments.create({
  amount: 1999,
  currency: 'EUR',
  method: 'bank_transfer',
  customer: 'cust_8Hk2mPq',
  mandate: 'mandate_4Tg1Lz',      // SEPA Direct Debit authorization
});

React to the result with webhooks

Because confirmation is asynchronous, webhooks — not the create response — are the source of truth.

export async function POST(req: Request) {
  const payload = await req.text();
  const signature = req.headers.get('x-vinr-signature')!;

  const event = vinr.webhooks.verify(payload, signature);

  switch (event.type) {
    case 'payment.completed':
      await fulfillOrder(event.data.metadata.invoiceId);
      break;
    case 'payment.failed':       // e.g. direct debit returned for insufficient funds
      await flagUnpaid(event.data.id);
      break;
  }

  return new Response('ok', { status: 200 });
}

Settlement & timingAskCopy

Once a transfer reaches completed, the funds enter your VINR balance and pay out on your normal settlement schedule. Two timings matter:

• Time to completion — how long until payment.completed. SEPA Instant and Faster Payments are near-real-time; standard SEPA and direct debit take days.
• Time to settlement — when the balance reaches your bank, governed by your payout schedule, independent of the rail.

Refunds & reversalsAskCopy

Refunds return funds to the originating account using the stored payout details. Create one against a completed payment:

const refund = await vinr.refunds.create({
  payment: 'pay_3Nf8x2a',
  amount: 49900,                 // omit for a full refund
  reason: 'requested_by_customer',
});
// refund.id → "re_6Pd9w1c", refund.status → "pending"

Bank refunds are themselves transfers, so they take 1–2 business days to land and fire refund.completed when done. Direct debit collections can also be returned by the customer's bank (e.g. no mandate, insufficient funds) after they appeared to succeed; VINR surfaces this as payment.failed and reverses the balance — design fulfillment to tolerate a clawback within the return window.

LimitationsAskCopy

• No instant authorization on push rails — never fulfill before payment.completed.
• Partial inbound amounts are held for review, not auto-completed.
• Direct debit requires a valid mandate and is subject to return windows.
• Disputes work differently than cards: there are no chargebacks on credit transfers, but direct debit returns can occur.

Next stepsAskCopy