@seamlessdocs/payment-modals 2.0.0-beta.8 → 2.0.0

package/README.md

@@ -1 +1,200 @@
-# Payment Modals
+# Payment Modals
+
+A React-based payment modal library for SeamlessDocs, providing a comprehensive set of reusable payment interface components for handling various payment workflows and user interactions.
+
+## Overview
+
+This library offers a collection of payment modals designed to streamline payment processing workflows. It supports multiple payment methods including ACH (bank account) and credit card payments, with integration capabilities for GovOS Pay payment processing.
+
+## Features
+
+- **Multiple Payment Methods**: Support for ACH and credit card payments
+- **GovOS Pay Integration**: Seamless integration with GovOS Pay payment processing
+- **Comprehensive Modal Set**: Includes modals for selection, processing, success, error, and payment forms
+- **React 18 Compatible**: Built with React 18 using the modern `createRoot` API
+- **Modular Architecture**: Component-based design with CSS modules for styling
+- **Form Validation**: Built-in form handling with Formik for payment forms
+- **Accessible UI**: Keyboard navigation and ARIA-compliant components
+
+## Available Modals
+
+### Payment Selection & Flow
+- **ChooseModal**: Allows users to choose between payment options
+- **SelectPaymentModal**: Payment method selection with fee display
+- **PayNowModal**: Direct payment initiation modal
+
+### Payment Forms
+- **ACHPaymentModal**: ACH/bank account payment form with fee breakdown
+- **GovOSPayACHPaymentModal**: GovOS Pay ACH payment integration
+- **GovOSPayCardPaymentModal**: GovOS Pay credit card payment integration
+- **GovOSPayInvoiceSummaryModal**: Invoice summary and confirmation for GovOS Pay
+
+### Status Modals
+- **ProcessingModal**: Displays during payment processing
+- **SuccessModal**: Confirmation message after successful payment
+- **ErrorModal**: Error handling with retry and skip options
+- **ErrorOptionalModal**: Optional error modal variant
+- **EmptyModal**: Empty state placeholder
+
+## Installation
+
+```bash
+npm install @seamlessdocs/payment-modals
+# or
+yarn add @seamlessdocs/payment-modals
+```
+
+## Usage
+
+The library exposes a global `handlePaymentModal` object that provides methods to render different modal types. Ensure you have a container element with the id `payment-modal` in your HTML:
+
+```html
+<div id="payment-modal"></div>
+```
+
+### Basic Example
+
+```javascript
+// Choose Modal
+window.handlePaymentModal.chooseModal({
+  title: 'Payment Required',
+  description: 'Please complete your payment',
+  withPayText: 'Pay Now',
+  callbacks: {
+    withoutPay: () => console.log('Skipped payment'),
+    withPay: () => console.log('Proceed to payment'),
+    close: () => console.log('Modal closed')
+  }
+});
+
+// ACH Payment Modal
+window.handlePaymentModal.achPaymentModal({
+  amount: 100.00,
+  totalAmount: 105.00,
+  feeAmount: 5.00,
+  description: 'Service fee',
+  feeName: 'Processing fee',
+  callbacks: {
+    onPay: (paymentData) => console.log('Payment submitted', paymentData),
+    onClose: () => console.log('Modal closed')
+  }
+});
+
+// Processing Modal
+window.handlePaymentModal.processingModal();
+
+// Success Modal
+window.handlePaymentModal.successModal({
+  description: 'Payment completed successfully'
+});
+
+// Error Modal
+window.handlePaymentModal.errorModal({
+  isOptional: false,
+  errorText: 'Payment failed. Please try again.',
+  callbacks: {
+    skip: () => console.log('Skipped'),
+    retry: () => console.log('Retry payment'),
+    close: () => console.log('Modal closed')
+  }
+});
+```
+
+### GovOS Pay Integration
+
+```javascript
+// GovOS Pay Card Payment
+window.handlePaymentModal.govOSPayCardPaymentModal({
+  amount: 100.00,
+  paymentCorrelationId: 'correlation-id',
+  paymentConfig: { /* Payrix config */ },
+  transactionMode: 'transaction', // or 'preauth'
+  transactionUrl: 'https://api.example.com/transactions',
+  getTransactionUrl: 'https://api.example.com/transactions/get',
+  updateTransactionUrl: 'https://api.example.com/transactions/update',
+  lineItems: [/* line items array */],
+  callbacks: {
+    onPay: (result) => console.log('Payment successful', result),
+    onClose: () => console.log('Modal closed')
+  }
+});
+
+// GovOS Pay ACH Payment
+window.handlePaymentModal.govOSPayACHPaymentModal({
+  amount: 100.00,
+  paymentCorrelationId: 'correlation-id',
+  paymentConfig: { /* Payrix config */ },
+  transactionUrl: 'https://api.example.com/transactions',
+  getTransactionUrl: 'https://api.example.com/transactions/get',
+  updateTransactionUrl: 'https://api.example.com/transactions/update',
+  lineItems: [/* line items array */],
+  callbacks: {
+    onPay: (result) => console.log('Payment successful', result),
+    onClose: () => console.log('Modal closed')
+  }
+});
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 22.0.0
+- Yarn or npm
+
+### Setup
+
+```bash
+# Install dependencies
+yarn install
+
+# Start development server
+yarn start
+
+# Build for development
+yarn dev
+
+# Build for production
+yarn build
+```
+
+### Project Structure
+
+```
+src/
+├── Components/          # Modal components
+│   ├── ACHPaymentModal/
+│   ├── ChooseModal/
+│   ├── ErrorModal/
+│   ├── GovOSPayACHPaymentModal/
+│   ├── GovOSPayCardPaymentModal/
+│   └── ...
+├── assets/             # Images and static assets
+├── index.jsx           # Main entry point
+└── shims.js            # Compatibility shims
+```
+
+## Dependencies
+
+### Core
+- React 18.2.0
+- React DOM 18.2.0
+- Formik 2.1.5 (form handling)
+- @kofile/platform-react-payrix 1.7.47 (GovOS Pay integration)
+
+### UI
+- react-select 5.8.0
+- @tippyjs/react 4.2.6
+- classnames 2.2.6
+
+## Browser Support
+
+Modern browsers with ES6+ support. The library uses React 18's `createRoot` API, which requires modern browser environments.
+
+## License
+
+Copyright © SeamlessDocs. All rights reserved.
+
+## Repository
+
+https://github.com/SeamlessDocsDev/PaymentModals