Declines & failures

When a payment ends in failed, VINR returns a structured failure object explaining why. This page maps those codes to root causes, separates retryable failures from permanent ones, and shows how to retry without burning through a customer's card or your decline rate.

Where the reason livesAskCopy

Every failed payment carries a failure object with a stable code, a human message, and a category you can branch on programmatically. The same object is attached to the payment.failed webhook.

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

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

const payment = await vinr.payments.retrieve('pay_3Kd9aZ2eRb');

if (payment.status === 'failed') {
  const { code, category, message, retryable } = payment.failure;
  console.log(`${category}/${code}: ${message} (retryable=${retryable})`);
}

Decline categoriesAskCopy

The category field groups every failure into one of five buckets. Branch on category for control flow; use code only for analytics.

Common codesAskCopy

Soft vs. hard declinesAskCopy

The single most important distinction for retry logic:

• Soft declines are temporary. The card is fundamentally usable but the bank said no right now — insufficient_funds, do_not_honor, processing_error. A later retry can succeed.
• Hard declines are permanent for that card. card_stolen, expired_card, pickup_card. Retrying the same card will fail again and repeated attempts hurt your authorization rate.

The failure.retryable boolean encodes this so you don't have to maintain the table yourself.

async function handleFailure(payment: any) {
  const { category, retryable } = payment.failure;

  if (!retryable) {
    // Hard decline — ask for a different payment method.
    return promptForNewCard(payment.customer);
  }
  if (category === 'processing_error') {
    return scheduleRetry(payment.id, { delayMs: 30_000 }); // transient: retry soon
  }
  // Soft issuer decline — retry on a smart schedule, not immediately.
  return scheduleRetry(payment.id, { delayMs: 24 * 60 * 60 * 1000 });
}

Retrying intelligentlyAskCopy

curl https://api.vinr.com/v1/payments \
  -H "X-Api-Key: $VINR_SECRET_KEY" \
  -H "Idempotency-Key: retry_pay_3Kd9aZ2eRb_attempt2" \
  -d amount=2500 \
  -d currency=eur \
  -d customer=cust_8Qm2 \
  -d payment_method=pm_1Lz4

Reducing decline ratesAskCopy

• Send full address and CVC. Issuers approve more often when AVS and CVC data are present.
• Pass a clear statement_descriptor. Cardholders dispute charges they don't recognise, and unfamiliar descriptors raise issuer suspicion.
• Use network tokens for saved cards. Tokenised credentials survive card reissues and lift approval rates versus raw PANs.
• Retry soft declines later, never harder. Volume of retries on a dead card lowers your overall acceptance rate.
• Test the paths. In sandbox, 4000 0000 0000 0002 forces a decline and 4000 0000 0000 3220 forces a 3DS challenge so you can exercise both branches.

Next stepsAskCopy