Complete database of Stripe decline codes with descriptions and localized messages
npm install stripe-decline-codes> Complete database of Stripe decline codes with descriptions and localized messages


A lightweight, zero-dependency TypeScript library providing human-readable descriptions and localized user messages for all Stripe payment decline codes.
- đ¯ Complete Coverage - All 44 Stripe decline codes included
- đ Localization - Built-in English and Japanese translations
- đ TypeScript Support - Full type definitions included
- đĒļ Zero Dependencies - Lightweight and fast
- đ Up-to-date - Based on Stripe API documentation (2024-12-18)
- â
Well Tested - Comprehensive test coverage
- đ¨ Message Formatting - Customizable message templates with variable substitution
This library is a complete TypeScript rewrite and continuation of the original stripe-utils package. The project has been:
- Renamed from stripe-utils to stripe-decline-codes to better reflect its focused scope
- Rewritten entirely in modern TypeScript with full type safety
- Modernized with current tooling (Vite, Biome, Vitest)
- Focused exclusively on Stripe decline code handling (subscription utilities removed)
- Updated with the latest Stripe decline codes (2024-12-18)
Credit to the original stripe-utils project for the initial implementation.
``bash`
npm install stripe-decline-codes
`typescript
import { getDeclineDescription } from 'stripe-decline-codes';
const result = getDeclineDescription('insufficient_funds');
console.log(result.code.description);
// => "The card has insufficient funds to complete the purchase."
console.log(result.code.nextUserAction);
// => "Please try again using an alternative payment method."
console.log(result.docVersion);
// => "2024-12-18"
`
Get user-facing messages in different languages:
`typescript
import { getDeclineMessage } from 'stripe-decline-codes';
// English (default)
const enMessage = getDeclineMessage('insufficient_funds');
console.log(enMessage);
// => "Please try again using an alternative payment method."
// Japanese
const jaMessage = getDeclineMessage('insufficient_funds', 'ja');
console.log(jaMessage);
// => "åĨãŽãæ¯æãæšæŗãäŊŋį¨ããĻããä¸åēĻãčŠĻããã ããã"
`
`typescript
import { isValidDeclineCode } from 'stripe-decline-codes';
isValidDeclineCode('insufficient_funds'); // => true
isValidDeclineCode('invalid_code'); // => false
`
`typescript
import { getAllDeclineCodes } from 'stripe-decline-codes';
const codes = getAllDeclineCodes();
console.log(codes.length); // => 44
console.log(codes);
// => ['approve_with_id', 'call_issuer', 'card_not_supported', ...]
`
Perfect for error handling in your Stripe integration:
`typescript
import Stripe from 'stripe';
import { getDeclineMessage } from 'stripe-decline-codes';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
try {
const charge = await stripe.charges.create({
amount: 2000,
currency: 'usd',
source: 'tok_chargeDeclined',
});
} catch (error) {
if (error.type === 'StripeCardError') {
const declineCode = error.decline_code;
const userMessage = getDeclineMessage(declineCode, 'en');
console.log(userMessage);
// Display this message to your user
}
}
`
#### getDeclineDescription(declineCode?: string): DeclineCodeResult
Returns detailed information about a decline code.
Returns:
`typescript`
{
docVersion: string;
code: {
description: string;
nextSteps: string;
nextUserAction: string;
translations?: {
ja?: {
description: string;
nextUserAction: string;
};
};
} | {};
}
#### getDeclineMessage(declineCode: string, locale?: Locale): string | undefined
Returns a localized user-facing message for a decline code.
Parameters:
- declineCode - The Stripe decline codelocale
- - The locale to use ('en' or 'ja', default: 'en')
#### getAllDeclineCodes(): DeclineCode[]
Returns an array of all supported decline code strings.
#### isValidDeclineCode(code: string): code is DeclineCode
Type guard to check if a string is a valid decline code.
#### getDocVersion(): string
Returns the Stripe API documentation version that this library is based on.
#### formatDeclineMessage(declineCode: string, locale?: Locale, variables?: Record
Returns a formatted message with optional variable substitution.
Example:
`typescript
import { formatDeclineMessage } from 'stripe-decline-codes';
const message = formatDeclineMessage('insufficient_funds', 'en', {
merchantName: 'Acme Store',
supportEmail: 'support@acme.com'
});
`
This library includes all 44 Stripe decline codes:
- approve_with_id - Payment cannot be authorizedcall_issuer
- - Card declined for unknown reasoncard_not_supported
- - Card doesn't support this purchase typecard_velocity_exceeded
- - Balance or credit limit exceededcurrency_not_supported
- - Card doesn't support the currencydo_not_honor
- - Card declined for unknown reasondo_not_try_again
- - Card declined for unknown reasonduplicate_transaction
- - Identical transaction submitted recentlyexpired_card
- - Card has expiredfraudulent
- - Payment suspected to be fraudulentgeneric_decline
- - Card declined for unknown reasonincorrect_number
- - Card number is incorrectincorrect_cvc
- - CVC number is incorrectincorrect_pin
- - PIN is incorrectincorrect_zip
- - ZIP/postal code is incorrectinsufficient_funds
- - Insufficient fundsinvalid_account
- - Card or account is invalidinvalid_amount
- - Payment amount is invalid or too largeinvalid_cvc
- - CVC number is incorrectinvalid_expiry_year
- - Expiration year is invalidinvalid_number
- - Card number is incorrectinvalid_pin
- - PIN is incorrectissuer_not_available
- - Card issuer could not be reachedlost_card
- - Card reported lostmerchant_blacklist
- - Payment matches merchant blocklistnew_account_information_available
- - Card or account is invalidno_action_taken
- - Card declined for unknown reasonnot_permitted
- - Payment is not permittedpickup_card
- - Card cannot be used for this paymentpin_try_exceeded
- - PIN attempts exceededprocessing_error
- - Error processing the cardreenter_transaction
- - Payment could not be processedrestricted_card
- - Card cannot be used for this paymentrevocation_of_all_authorizations
- - Card declinedrevocation_of_authorization
- - Card declinedsecurity_violation
- - Card declinedservice_not_allowed
- - Card declinedstolen_card
- - Card reported stolenstop_payment_order
- - Card declinedtestmode_decline
- - Stripe test card usedtransaction_not_allowed
- - Card declinedtry_again_later
- - Card declined, try again laterwithdrawal_count_limit_exceeded
- - Credit limit exceeded
This library is written in TypeScript and includes full type definitions:
`typescript`
import type {
DeclineCode,
DeclineCodeInfo,
DeclineCodeResult,
Locale,
Translation,
} from 'stripe-decline-codes';
`bashInstall dependencies
npm install
Publishing
np for releases:`bash
npm run release
``Contributions are welcome! Please feel free to submit a Pull Request.
MIT Š Hidetaka Okamoto
- Stripe API Documentation
- Stripe Node.js Library
- Forked and renewed from stripe-utils
- Complete rewrite in TypeScript
- Modern build system with Vite + Biome
- Added comprehensive type definitions
- Updated to latest Stripe decline codes (2024-12-18)
- Zero dependencies
- Enhanced API with new utility functions
- Improved documentation