@venturialstd/fintech

A comprehensive NestJS module for building fintech platforms with support for multi-currency operations, transactions, beneficiaries, and payment providers.

Features

• Multi-Currency Support: Manage multiple currencies (fiat and crypto) with automatic exchange rate tracking
• Account Management: Create and manage user accounts with KYC verification support
• Balance Tracking: Real-time balance management with available and pending balances
• Operations: Support for deposits, withdrawals, transfers, payments, and refunds
• Transactions: Track transactions through multiple providers with detailed status tracking
• Beneficiaries: Manage saved beneficiaries with multiple account types (bank, card, wallet, crypto)
• Provider Integration: Support for multiple payment providers with configurable settings
• Comprehensive Status Tracking: Track every operation and transaction through its lifecycle

Installation

npm install @venturialstd/fintech

Usage

Import the Module

import { Module } from '@nestjs/common';
import { FintechModule } from '@venturialstd/fintech';

@Module({
  imports: [FintechModule],
})
export class AppModule {}

Core Entities

Currency

Represents supported currencies (USD, EUR, BTC, etc.) with exchange rates.

{
  code: 'USD',
  name: 'US Dollar',
  symbol: '$',
  type: CURRENCY_TYPE.FIAT,
  decimalPlaces: 2,
  exchangeRateToUSD: 1.0
}

Provider

Payment providers (Stripe, PayPal, Wise, etc.) that process transactions.

{
  name: 'Stripe',
  code: 'STRIPE',
  type: PROVIDER_TYPE.PAYMENT_GATEWAY,
  supportsDeposit: true,
  supportsWithdrawal: true,
  supportedCurrencies: ['USD', 'EUR', 'GBP']
}

Account

User accounts that hold balances in different currencies.

{
  userId: 'user-123',
  accountNumber: 'ACC-001',
  type: ACCOUNT_TYPE.PERSONAL,
  status: ACCOUNT_STATUS.ACTIVE,
  isVerified: true
}

Balance

Tracks available and pending balances for an account in a specific currency.

{
  accountId: 'account-id',
  currencyId: 'currency-id',
  availableBalance: 1000.00,
  pendingBalance: 50.00,
  totalBalance: 1050.00
}

Operation

High-level financial operations (deposit, withdrawal, transfer).

{
  type: OPERATION_TYPE.WITHDRAWAL,
  accountId: 'account-id',
  currencyId: 'currency-id',
  amount: 100.00,
  fee: 2.50,
  totalAmount: 102.50,
  status: OPERATION_STATUS.COMPLETED
}

Transaction

Individual transactions with providers that make up an operation.

{
  operationId: 'operation-id',
  providerId: 'provider-id',
  type: TRANSACTION_TYPE.DEBIT,
  status: TRANSACTION_STATUS.COMPLETED,
  amount: 102.50,
  externalTransactionId: 'stripe-tx-123'
}

Beneficiary

Saved recipients for withdrawals and transfers.

{
  accountId: 'account-id',
  name: 'John Doe',
  type: BENEFICIARY_TYPE.PERSONAL,
  status: BENEFICIARY_STATUS.VERIFIED,
  email: '[email protected]'
}

BeneficiaryAccount

Bank account, card, or wallet information for a beneficiary.

{
  beneficiaryId: 'beneficiary-id',
  type: BENEFICIARY_ACCOUNT_TYPE.BANK_ACCOUNT,
  currencyId: 'currency-id',
  country: COUNTRY_CODE.US,
  accountNumber: '1234567890',
  routingNumber: '021000021',
  bankName: 'Chase Bank'
}

Services

All services extend TypeOrmCrudService from @dataui/crud-typeorm for consistent CRUD operations.

CurrencyService

• getCurrencyByCode(code: string)
• getActiveCurrencies()
• updateExchangeRate(currencyId: string, rate: number)

ProviderService

• getProviderByCode(code: string)
• getActiveProviders()
• getProvidersByCurrency(currencyCode: string)
• updateProviderStatus(providerId: string, status: PROVIDER_STATUS)

AccountService

• getAccountsByUserId(userId: string)
• getAccountByNumber(accountNumber: string)
• updateAccountStatus(accountId: string, status: ACCOUNT_STATUS)
• verifyAccount(accountId: string, verificationLevel: string)
• getActiveAccounts(userId: string)

BalanceService

• getBalanceByAccountAndCurrency(accountId: string, currencyId: string)
• getBalancesByAccount(accountId: string)
• addToBalance(accountId: string, currencyId: string, amount: number)
• subtractFromBalance(accountId: string, currencyId: string, amount: number)

OperationService

• getOperationsByAccount(accountId: string)
• getOperationsByType(accountId: string, type: OPERATION_TYPE)
• getOperationsByStatus(accountId: string, status: OPERATION_STATUS)
• updateOperationStatus(operationId: string, status: OPERATION_STATUS)
• getPendingOperations()

TransactionService

• getTransactionsByOperation(operationId: string)
• getTransactionsByProvider(providerId: string)
• updateTransactionStatus(transactionId: string, status: TRANSACTION_STATUS)

BeneficiaryService

• getBeneficiariesByAccount(accountId: string)
• getVerifiedBeneficiaries(accountId: string)
• updateBeneficiaryStatus(beneficiaryId: string, status: BENEFICIARY_STATUS)

BeneficiaryAccountService

• getAccountsByBeneficiary(beneficiaryId: string)
• getDefaultAccount(beneficiaryId: string)
• setDefaultAccount(accountId: string)
• getActiveAccounts(beneficiaryId: string)

Testing

The module includes a comprehensive test application that you can run locally.

Setup

1. Copy the example environment file:

cd test
cp .env.example .env

2. Update the .env file with your database credentials.

3. Run migrations:

npm run migration:run

4. Start the test server:

npm run test:dev

The test server will start on http://localhost:3003 with all endpoints available for testing.

Available Scripts

• npm run build - Build the module
• npm run test:dev - Start the test server
• npm run test:watch - Start the test server with auto-reload
• npm run migration:generate --name=MigrationName - Generate a new migration
• npm run migration:run - Run pending migrations
• npm run migration:revert - Revert the last migration

Example Usage

Creating a Deposit Operation

import { OperationService, BalanceService } from '@venturialstd/fintech';

// Create a deposit operation
const operation = await operationService.repo.save({
  type: OPERATION_TYPE.DEPOSIT,
  accountId: 'account-id',
  currencyId: 'usd-id',
  amount: 100.00,
  fee: 0,
  totalAmount: 100.00,
  status: OPERATION_STATUS.PENDING,
});

// Add to balance when completed
await balanceService.addToBalance('account-id', 'usd-id', 100.00);

// Update operation status
await operationService.updateOperationStatus(
  operation.id,
  OPERATION_STATUS.COMPLETED
);

Creating a Withdrawal with Provider

// Create withdrawal operation
const operation = await operationService.repo.save({
  type: OPERATION_TYPE.WITHDRAWAL,
  accountId: 'account-id',
  currencyId: 'usd-id',
  amount: 100.00,
  fee: 2.50,
  totalAmount: 102.50,
  beneficiaryId: 'beneficiary-id',
});

// Create transaction with provider
const transaction = await transactionService.repo.save({
  operationId: operation.id,
  providerId: 'stripe-id',
  type: TRANSACTION_TYPE.DEBIT,
  currencyId: 'usd-id',
  amount: 102.50,
  sequence: 1,
});

// Process through provider...
// Update transaction status
await transactionService.updateTransactionStatus(
  transaction.id,
  TRANSACTION_STATUS.COMPLETED,
  { stripeResponse: {...} }
);

// Subtract from balance
await balanceService.subtractFromBalance('account-id', 'usd-id', 102.50);

// Update operation
await operationService.updateOperationStatus(
  operation.id,
  OPERATION_STATUS.COMPLETED
);

License

MIT

Support

For issues and questions, please open an issue on the repository.