@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

``bash
npm install @venturialstd/fintech
`

Usage

$3

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

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

$3

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

`typescript
{
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.

`typescript
{
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.

`typescript
{
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.

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

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

`typescript
{
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.

`typescript
{
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.

`typescript
{
accountId: 'account-id',
name: 'John Doe',
type: BENEFICIARY_TYPE.PERSONAL,
status: BENEFICIARY_STATUS.VERIFIED,
email: 'john@example.com'
}
`

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

`typescript
{
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.

$3


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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

- 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.

$3

1. Copy the example environment file:
`bash
cd test
cp .env.example .env
`

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

3. Run migrations:
`bash
npm run migration:run
`

4. Start the test server:
`bash
npm run test:dev
`

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

$3

- 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

$3

`typescript
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
);
`

$3

`typescript
// 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.