PaySeed 💳

A comprehensive TypeScript library for payment processing utilities

PaySeed is a lightweight, type-safe library providing essential utilities for payment processing, money formatting, credit card validation, and fee calculations.

✨ Features

• 💰 Money Formatting - Format and parse money values with multiple currency support
• 💳 Card Validation - Validate and identify credit card brands using Luhn algorithm
• 🧮 Fee Calculations - Calculate processing fees with percentage and fixed components
• 🌍 Multi-Currency - Support for USD, EUR, GBP, JPY, CAD, AUD, CHF, CNY
• 🔒 Type-Safe - Full TypeScript support with comprehensive type definitions
• ⚡ Zero Dependencies - Lightweight and fast
• ✅ Well Tested - 100% test coverage

📦 Installation

npm install payseed
# or
yarn add payseed
# or
pnpm add payseed

🚀 Quick Start

import { formatMoney, validateCardNumber, calculateProcessingFee } from 'payseed';

// Format money
const money = { amount: 1234, currency: 'USD' as const };
console.log(formatMoney(money)); // "USD 12.34"

// Validate credit card
const isValid = validateCardNumber('4111111111111111');
console.log(isValid); // true

// Calculate processing fee (2.9% + $0.30)
const fee = calculateProcessingFee(10000, 2.9, 30);
console.log(fee); // 320 (in cents)

📖 API Reference

Money Utilities

formatMoney(money: Money): string

Format money object to display string.

formatMoney({ amount: 1234, currency: 'USD' }); // "USD 12.34"

formatCurrency(amount: number, currency: CurrencyCode, locale?: string): string

Format with locale support using Intl.NumberFormat.

formatCurrency(1234, 'USD'); // "$12.34"
formatCurrency(1000, 'JPY'); // "¥1,000"

parseMoney(moneyString: string, currency: CurrencyCode): Money

Parse money string to Money object.

parseMoney('$12.34', 'USD'); // { amount: 1234, currency: 'USD' }

toMinorUnits(amount: number, decimals?: number): number

Convert major units to minor units (e.g., dollars to cents).

toMinorUnits(10.50); // 1050
toMinorUnits(100, 0); // 100 (for JPY)

toMajorUnits(amount: number, decimals?: number): number

Convert minor units to major units (e.g., cents to dollars).

toMajorUnits(1050); // 10.50

Credit Card Utilities

validateCardNumber(cardNumber: string): boolean

Validate card number using Luhn algorithm.

validateCardNumber('4111111111111111'); // true (Valid Visa)
validateCardNumber('4111-1111-1111-1111'); // true (handles formatting)

identifyCardBrand(cardNumber: string): CardBrand

Identify credit card brand from number.

identifyCardBrand('4242424242424242'); // 'visa'
identifyCardBrand('5555555555554444'); // 'mastercard'
identifyCardBrand('378282246310005'); // 'amex'

maskCardNumber(cardNumber: string): string

Mask credit card number for display.

maskCardNumber('4111111111111111'); // '************1111'
maskCardNumber('378282246310005'); // '***********0005'

Fee Calculation

calculateFee(amount: number, percentage: number): number

Calculate simple percentage fee.

calculateFee(10000, 2.9); // 290

calculateProcessingFee(amount: number, percentageFee: number, fixedFee?: number): number

Calculate payment processing fee with fixed and percentage components.

calculateProcessingFee(10000, 2.9, 30); // 320 (2.9% + $0.30)

Money Arithmetic

addMoney(a: Money, b: Money): Money

Add two money values (must be same currency).

const sum = addMoney(
  { amount: 1000, currency: 'USD' },
  { amount: 500, currency: 'USD' }
); // { amount: 1500, currency: 'USD' }

subtractMoney(a: Money, b: Money): Money

Subtract two money values.

const diff = subtractMoney(
  { amount: 1000, currency: 'USD' },
  { amount: 300, currency: 'USD' }
); // { amount: 700, currency: 'USD' }

multiplyMoney(money: Money, factor: number): Money

Multiply money by a factor.

const doubled = multiplyMoney(
  { amount: 1000, currency: 'USD' },
  2
); // { amount: 2000, currency: 'USD' }

Utility Functions

seedId(prefix?: string): string

Generate unique payment-related ID.

seedId(); // 'payseed_lq3x8n2k_a7b9c2'
seedId('transaction'); // 'transaction_lq3x8n2k_a7b9c2'

paymentReference(type?: 'invoice' | 'order' | 'payment'): string

Generate formatted payment reference.

paymentReference(); // 'PAY-LQ3X8N2K-A7B9C2'
paymentReference('invoice'); // 'INV-LQ3X8N2K-A7B9C2'

isZeroMoney(money: Money): boolean

Check if money amount is zero.

isZeroMoney({ amount: 0, currency: 'USD' }); // true

isNegativeMoney(money: Money): boolean

Check if money amount is negative.

isNegativeMoney({ amount: -100, currency: 'USD' }); // true

🎯 Use Cases

PaySeed is perfect for:

• E-commerce applications
• Payment processing systems
• Financial dashboards
• Invoice generation
• Shopping carts
• Subscription billing
• Any application handling money

🧪 Testing

# Run tests
pnpm test

# Run tests with coverage
pnpm test:ci

📝 License

MIT © [Your Name]

🤝 Contributing

Contributions, issues and feature requests are welcome!

⭐ Show your support

Give a ⭐️ if this project helped you!