Save a payment method

There are two ways to save a payment method: during a payment using setup_future_usage, or without charging using a Setup flow when you want to collect and vault card details upfront.

Save during a paymentAskCopy

Add setup_future_usage to a payment to save the payment method used for that charge:

• on_session — saves the method for future checkouts where the customer will be present on your site.
• off_session — saves the method for background charges (subscriptions, reorders) where the customer will not be present. VINR requests stronger authentication upfront so future off-session charges can proceed without additional friction.

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

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

const payment = await vinr.payments.create({
  amount: 2900,
  currency: 'EUR',
  customer: 'cus_ABC123',
  setupFutureUsage: 'off_session',  // or 'on_session'
  method: 'card',
  returnUrl: 'https://yoursite.com/checkout/complete',
});

After the payment completes, retrieve the PaymentMethod ID from the payment object and store it against your customer record:

const completedPayment = await vinr.payments.retrieve('pay_ABC123');
const savedMethodId = completedPayment.paymentMethodId; // → "pm_XYZ789"

Save without charging (Setup flow)AskCopy

Use a SetupIntent when you want to vault a payment method without an immediate charge — for example, at trial sign-up or when a customer adds a card to their account settings.

const setupIntent = await vinr.setupIntents.create({
  customer: 'cus_ABC123',
  usage: 'off_session',          // or 'on_session'
});

// Return setupIntent.clientSecret to the client

if (event.type === 'payment_method.attached') {
  const paymentMethod = event.data.object;
  await db.customers.updatePaymentMethod(paymentMethod.customer, paymentMethod.id);
}

List and remove saved methodsAskCopy

List all saved payment methods for a customer:

const methods = await vinr.customers.listPaymentMethods('cus_ABC123', {
  type: 'card',
});

for (const method of methods.data) {
  console.log(method.id, method.card?.brand, method.card?.last4);
}

Remove a method when a customer deletes a saved card from their account:

await vinr.paymentMethods.detach('pm_XYZ789');
// The method is removed from the customer and can no longer be charged

See alsoAskCopy