How payments work

A VINR payment moves through a predictable set of objects and states regardless of which rail it uses — card, bank transfer, stablecoin, or a local method. Learn this model once and every method, capability, and API endpoint becomes easier to reason about.

The payment objectAskCopy

Every charge is represented by a single payment object. You create it with an amount in minor units (e.g. 1000 = €10.00), a currency, and where to send the customer afterward.

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

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

const payment = await vinr.payments.create({
  amount: 1000,            // €10.00 in minor units
  currency: 'EUR',
  description: 'Order #1234',
  returnUrl: 'https://yoursite.com/payment/complete',
  metadata: { orderId: '1234' },
});

// payment.id        → "pay_3Nf8x2a..."
// payment.status    → "pending"
// payment.checkoutUrl → hosted page to send the customer to

Rails & methodsAskCopy

A rail is the underlying network that moves the money; a method is what the customer chooses. One integration gives you all of them — see Payment methods.

Authorization vs. captureAskCopy

For card payments, money moves in up to two steps:

1. Authorization — the issuer reserves the funds on the customer's account.
2. Capture — you claim the reserved funds, moving them toward settlement.

By default VINR captures immediately. To reserve now and capture later (e.g. on shipment), use authorize & capture.

Funds flow & settlementAskCopy

customer → [authorization] → [capture] → your VINR balance → [settlement] → your bank

Captured funds accumulate in your balance and are paid out to your bank on your settlement schedule. Fees and refunds are netted along the way and reflected in reconciliation.

Where to go nextAskCopy