npm package: @seamlessdocs/payment-modals
Description: Payment modals for SeamlessDocs
Latest version: 2.0.1

# 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