@dbs-portal/module-payment

Payment processing and management module for DBS Portal. Provides comprehensive payment functionality including transaction processing, payment methods, invoices, subscriptions, and analytics.

Features

🚀 Core Features

• Payment Transaction Management: Process, capture, void, and refund payments with multiple gateway support
• Payment Method Management: Secure storage and management of credit cards, bank accounts, and digital wallets
• Invoice Generation: Create, send, and track invoices with automated payment processing
• Subscription Billing: Recurring payment management with flexible billing cycles and plans
• Multi-Gateway Support: Integrate with Stripe, PayPal, Square, and other payment providers
• Multi-Currency Support: Handle payments in multiple currencies with proper formatting
• Analytics Dashboard: Comprehensive payment analytics with revenue insights and performance metrics

🎨 UI Components

• PaymentTransactionList: List and manage payment transactions with filtering and bulk operations
• PaymentMethodList: Manage payment methods with verification status and usage tracking
• PaymentAnalyticsDashboard: Comprehensive analytics with revenue metrics and gateway performance
• InvoiceList: Invoice management with payment tracking and automated reminders
• SubscriptionList: Subscription management with billing cycle tracking
• PaymentCustomerList: Customer management with payment history and risk assessment

🔧 Technical Features

• React Query Integration: Optimized data fetching with caching and real-time updates
• TypeScript Support: Full type safety with comprehensive type definitions
• Service Layer: Clean API abstraction with error handling and retry logic
• Security: PCI-compliant payment processing with tokenization and encryption
• Responsive Design: Mobile-friendly UI components using Ant Design
• Real-time Updates: Live transaction status updates and webhook handling

Installation

yarn add @dbs-portal/module-payment

Dependencies

This module requires the following peer dependencies:

yarn add react react-dom antd @ant-design/icons @tanstack/react-query date-fns lodash-es decimal.js

Usage

Basic Setup

import React from 'react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import {
  PaymentTransactionList,
  PaymentAnalyticsDashboard,
  usePaymentTransactions,
  payment
} from '@dbs-portal/module-payment'

const queryClient = new QueryClient()

function PaymentApp() {
  return (
    <QueryClientProvider client={queryClient}>
      <div>
        <PaymentAnalyticsDashboard />
        <PaymentTransactionList />
      </div>
    </QueryClientProvider>
  )
}

Using React Query Hooks

import { usePaymentTransactions, useProcessPayment } from '@dbs-portal/module-payment'

function PaymentManager() {
  const { data: transactions, isLoading } = usePaymentTransactions({
    page: 1,
    pageSize: 10,
    status: 'completed'
  })

  const processPaymentMutation = useProcessPayment()

  const handleProcessPayment = async (paymentData) => {
    try {
      const result = await processPaymentMutation.mutateAsync(paymentData)
      console.log('Payment processed:', result)
    } catch (error) {
      console.error('Payment failed:', error)
    }
  }

  if (isLoading) return <div>Loading...</div>

  return (
    <div>
      {transactions?.items.map(transaction => (
        <div key={transaction.id}>{transaction.transactionId}</div>
      ))}
    </div>
  )
}

Using Services Directly

import { payment } from '@dbs-portal/module-payment'

// Process a payment
const result = await payment.transactions.processPayment({
  amount: { amount: '100.00', currency: 'USD' },
  paymentMethodId: 'pm_123',
  customerId: 'cust_456'
})

// Create a payment method
const paymentMethod = await payment.methods.createPaymentMethod({
  type: 'credit_card',
  customerId: 'cust_456',
  cardNumber: '4242424242424242',
  cardExpMonth: 12,
  cardExpYear: 2025,
  cardCvc: '123'
})

// Create an invoice
const invoice = await payment.invoices.createInvoice({
  customerId: 'cust_456',
  items: [{
    description: 'Product A',
    quantity: 1,
    unitPrice: { amount: '100.00', currency: 'USD' }
  }]
})

Using Payment Utilities

import { PaymentUtils } from '@dbs-portal/module-payment'

// Format money
const formatted = PaymentUtils.formatMoney({
  amount: '1234.56',
  currency: 'USD'
}) // "USD 1234.56"

// Validate credit card
const isValid = PaymentUtils.validateCreditCard('4242424242424242') // true

// Get card brand
const brand = PaymentUtils.getCreditCardBrand('4242424242424242') // 'visa'

// Mask card number
const masked = PaymentUtils.maskCreditCard('4242424242424242') // '•••• •••• •••• 4242'

Components

PaymentTransactionList

List and manage payment transactions with filtering and bulk operations.

import { PaymentTransactionList } from '@dbs-portal/module-payment'

<PaymentTransactionList
  onTransactionSelect={(transaction) => console.log('Selected:', transaction)}
  onTransactionView={(transaction) => console.log('View:', transaction)}
  showActions={true}
  selectable={true}
/>

PaymentMethodList

Manage payment methods with verification and usage tracking.

import { PaymentMethodList } from '@dbs-portal/module-payment'

<PaymentMethodList
  customerId="cust_123" // Optional to filter by customer
  onMethodSelect={(method) => console.log('Selected:', method)}
  onMethodEdit={(method) => console.log('Edit:', method)}
  onMethodCreate={() => console.log('Create new method')}
  showActions={true}
/>

PaymentAnalyticsDashboard

Comprehensive payment analytics and insights.

import { PaymentAnalyticsDashboard } from '@dbs-portal/module-payment'

<PaymentAnalyticsDashboard />

React Query Hooks

Payment Transactions

// Get paginated transactions
const { data, isLoading } = usePaymentTransactions(params)

// Get single transaction
const { data: transaction } = usePaymentTransaction(transactionId)

// Get transaction with relations
const { data: transactionWithRelations } = usePaymentTransactionWithRelations(transactionId)

// Get transactions by customer
const { data: customerTransactions } = useTransactionsByCustomer(customerId)

// Mutations
const processPayment = useProcessPayment()
const refundTransaction = useRefundTransaction()
const voidTransaction = useVoidTransaction()
const captureTransaction = useCaptureTransaction()

Payment Methods

// Get payment methods
const { data: methods } = usePaymentMethods(params)

// Get methods by customer
const { data: customerMethods } = usePaymentMethodsByCustomer(customerId)

// Get default payment method
const { data: defaultMethod } = useDefaultPaymentMethod(customerId)

// Mutations
const createMethod = useCreatePaymentMethod()
const updateMethod = useUpdatePaymentMethod()
const deleteMethod = useDeletePaymentMethod()
const setDefault = useSetDefaultPaymentMethod()

Invoices

// Get invoices
const { data: invoices } = useInvoices(params)

// Get single invoice
const { data: invoice } = useInvoice(invoiceId)

// Get overdue invoices
const { data: overdue } = useOverdueInvoices()

// Mutations
const createInvoice = useCreateInvoice()
const sendInvoice = useSendInvoice()
const markAsPaid = useMarkInvoiceAsPaid()

Types

The module exports comprehensive TypeScript types:

import type {
  PaymentTransaction,
  PaymentMethod,
  Invoice,
  Subscription,
  PaymentCustomer,
  PaymentAnalytics,
  PaymentStatus,
  PaymentMethodType,
  PaymentGateway,
  Money,
  CreatePaymentTransactionDto,
  ProcessPaymentDto
} from '@dbs-portal/module-payment'

API Integration

The module uses a service layer that integrates with your backend API. All services expect standard REST endpoints:

• GET /api/payment/transactions - Get payment transactions
• POST /api/payment/transactions/process - Process payment
• POST /api/payment/transactions/:id/refund - Refund transaction
• GET /api/payment/methods - Get payment methods
• POST /api/payment/methods - Create payment method
• GET /api/payment/invoices - Get invoices
• POST /api/payment/invoices - Create invoice

Security

The payment module follows PCI compliance standards:

• Tokenization: Sensitive payment data is tokenized
• Encryption: All data is encrypted in transit and at rest
• Validation: Client-side validation with server-side verification
• Audit Trail: Complete transaction logging and monitoring

Contributing

This module follows the DBS Portal Phase 4 business module standards:

• Complete TypeScript types system
• Service layer with CRUD operations
• React Query hooks for data fetching
• UI components with Ant Design
• Zero linting errors
• Proper monorepo integration

License

Private - DBS Portal internal use only.

Installation

yarn add @dbs-portal/module-payment

Usage

import { Payment, createPayment } from '@dbs-portal/module-payment'

// Use the default instance
const result = await defaultPayment.process(data)

// Or create a custom instance
const customPayment = createPayment({
  enabled: true,
  debug: true,
})

const customResult = await customPayment.process(data)

API Reference

Classes

Payment

Main class for @dbs-portal/module-payment functionality.

Constructor:

• new Payment(config?: PaymentConfig)

Methods:

• getConfig(): PaymentConfig - Get current configuration
• process<T>(data: T): Promise<PaymentResult<T>> - Process data

Functions

createPayment(config?)

Factory function to create a new Payment instance.

Development

# Build the package
yarn build

# Run tests
yarn test

# Type checking
yarn type-check

# Linting
yarn lint