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

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:

<div id="payment-modal"></div>

Basic Example

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

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

# 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