Fintech Platform Module for Venturial
npm install @venturialstd/fintechA comprehensive NestJS module for building fintech platforms with support for multi-currency operations, transactions, beneficiaries, and payment providers.
- 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
``bash`
npm install @venturialstd/fintech
`typescript
import { Module } from '@nestjs/common';
import { FintechModule } from '@venturialstd/fintech';
@Module({
imports: [FintechModule],
})
export class AppModule {}
`
#### 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'
}
All services extend TypeOrmCrudService from @dataui/crud-typeorm for consistent CRUD operations.
- 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 migrationExample 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
);
``MIT
For issues and questions, please open an issue on the repository.