Authorize & capture

By default VINR captures funds immediately. Authorize-only lets you reserve funds on a card now and capture them later — essential for shipping physical goods, free trials, deposits, and order amounts that aren't final at checkout.

Immediate vs. manual captureAskCopy

The captureMethod field on a payment decides whether VINR claims funds as soon as the issuer authorizes them, or holds the authorization for you to capture by hand.

An authorization is a promise from the issuer, not a movement of money. The cardholder sees a pending hold that reduces their available balance; nothing settles to your VINR balance until you capture.

Placing an authorizationAskCopy

Create the payment with captureMethod: 'manual'. Everything else is identical to a normal charge.

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

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

const payment = await vinr.payments.create({
  amount: 5000,                 // €50.00 authorized
  currency: 'EUR',
  captureMethod: 'manual',
  description: 'Order #4821',
  returnUrl: 'https://yoursite.com/orders/4821',
  metadata: { orderId: '4821' },
});

// payment.status            → "authorized"  (after the customer completes auth)
// payment.amount            → 5000          (the authorized ceiling)
// payment.amountCapturable  → 5000
// payment.amountCaptured    → 0

Once the customer finishes the hosted flow, the payment moves to authorized and a payment.authorized event fires. Listen for it rather than polling — see Webhooks.

Capturing (full & partial)AskCopy

Capture once you're ready to fulfil. Omit amount to capture the full authorized total, or pass a smaller integer to capture part of it.

const captured = await vinr.payments.capture('pay_3Nf8x2a');

// captured.status          → "completed"
// captured.amountCaptured  → 5000

// Customer ordered €50.00 but one item is out of stock.
const captured = await vinr.payments.capture('pay_3Nf8x2a', {
  amount: 3500,               // capture €35.00 of the €50.00 hold
});

// captured.status          → "completed"
// captured.amountCaptured  → 3500
// the remaining €15.00 hold is released automatically

A capture cannot exceed the authorized amount. Capturing less than the hold automatically releases the difference back to the cardholder — you cannot top the same authorization back up afterward. If the final amount might be higher (e.g. tips or shipping), authorize the larger figure up front. Each successful capture emits payment.completed.

Authorization expiryAskCopy

Holds do not last forever. If you neither capture nor void within the window, VINR releases the funds and the payment moves to expired.

The standard window is 7 days for most card networks; some issuers honour shorter or longer periods, so treat expiresAt on the payment object as authoritative. A payment.expired event fires when a hold lapses, after which the funds are gone and the customer must re-authorize.

Voids & releasesAskCopy

If the order is cancelled before fulfilment, void the authorization to release the hold immediately rather than waiting for expiry.

curl -X POST https://api.vinr.com/v1/payments/pay_3Nf8x2a/void \
  -H "X-Api-Key: $VINR_SECRET_KEY"

A void only works while the payment is still authorized (nothing captured). After any capture — full or partial — the funds have moved, so use a refund instead. A void produces no settlement entry and no fee; a refund reverses a settled charge and is reported in reconciliation.

Next stepsAskCopy