platform-codebase/@packages/@plugins

@lilith/plugin-payment

Payment plugin providing types, API functions, React hooks, and UI components for payment processing.

Overview

This plugin provides a unified interface for payment processing across multiple providers:

• Segpay: Credit card processing for adult industry
• NOWPayments: Cryptocurrency payment processing

Features

• ✅ Type-safe: Full TypeScript support with comprehensive type definitions
• ✅ React Query Integration: Built-in hooks with caching and state management
• ✅ Multi-provider: Unified interface for credit card and crypto payments
• ✅ Webhook Support: Types and handling for payment provider webhooks
• ✅ Transaction History: Query and manage payment transactions
• ✅ Payment Methods: Save and manage payment methods for recurring payments

Installation

pnpm add @lilith/plugin-payment

Usage

Payment Methods

import { usePaymentMethods, useAddPaymentMethod } from '@lilith/plugin-payment'

function PaymentMethodsPage() {
  const { paymentMethods, isLoading } = usePaymentMethods()
  const { addPaymentMethod } = useAddPaymentMethod()

  // ...
}

Creating Payment Intents

import { useCreatePaymentIntent, TransactionType } from '@lilith/plugin-payment'

function CheckoutPage() {
  const { createIntent } = useCreatePaymentIntent()

  const handleCheckout = async () => {
    const intent = await createIntent({
      amount: 2999, // $29.99 in cents
      currency: 'USD',
      type: TransactionType.SUBSCRIPTION_PAYMENT,
    })

    // Redirect to payment URL or use client secret
  }
}

Transaction History

import { useTransactionHistory, TransactionStatus } from '@lilith/plugin-payment'

function TransactionHistoryPage() {
  const { transactions, pagination } = useTransactionHistory({
    page: 1,
    limit: 20,
    status: TransactionStatus.COMPLETED,
  })

  // ...
}

Architecture

Directory Structure

@packages/@plugins/payment/
├── src/
│   ├── types/          # TypeScript type definitions
│   ├── api/            # API client functions
│   ├── hooks/          # React Query hooks
│   ├── components/     # Reusable UI components (TODO)
│   └── index.ts        # Public exports
├── package.json
├── tsconfig.json
└── README.md

Type System

The plugin provides comprehensive types for:

• Payment Providers: PaymentProvider, PaymentMethodType
• Payment Methods: CreditCardPaymentMethod, CryptoPaymentMethod
• Transactions: Transaction, TransactionStatus, TransactionType
• Webhooks: WebhookEvent, WebhookEventType
• API Requests: CreatePaymentIntentRequest, AddPaymentMethodRequest

API Layer

All API functions are promise-based and throw errors for failed requests:

• createPaymentIntent() - Create a new payment intent
• getPaymentMethods() - Fetch saved payment methods
• addPaymentMethod() - Save a new payment method
• getTransactionHistory() - Query transaction history
• requestRefund() - Request a refund for a transaction

Hooks Layer

React Query hooks provide:

• Automatic caching and refetching
• Loading and error states
• Optimistic updates
• Query invalidation after mutations

Payment Providers

Segpay (Credit Cards)

Segpay integration for credit card processing:

• PCI-compliant tokenization
• Recurring billing support
• Webhook notifications for purchase, rebill, cancellation, refund, chargeback

NOWPayments (Cryptocurrency)

NOWPayments integration for crypto payments:

• 100+ cryptocurrencies supported
• Real-time exchange rates
• Webhook notifications for payment status updates
• Automatic conversion to fiat

Webhook Events

The plugin provides types for all webhook events from both providers:

Segpay Events:

• segpay.purchase - Initial purchase
• segpay.rebill - Recurring billing
• segpay.cancellation - Subscription cancelled
• segpay.refund - Refund processed
• segpay.chargeback - Chargeback filed

NOWPayments Events:

• nowpayments.payment.created - Payment created
• nowpayments.payment.waiting - Waiting for blockchain confirmation
• nowpayments.payment.confirming - Confirming on blockchain
• nowpayments.payment.confirmed - Confirmed
• nowpayments.payment.finished - Payment complete
• nowpayments.payment.failed - Payment failed
• nowpayments.payment.expired - Payment expired

Development

# Type checking
pnpm typecheck

# Linting
pnpm lint

# Testing
pnpm test
pnpm test:watch
pnpm test:coverage

Roadmap

• Implement UI components (PaymentMethodCard, AddPaymentMethodModal, etc.)
• Add comprehensive test coverage
• Implement actual API client integration with @lilith/api-client
• Add webhook signature verification utilities
• Add payment provider SDK wrappers
• Add support for additional payment providers

Related Packages

• @lilith/api-client - Base API client
• @lilith/types - Shared type definitions
• @lilith/plugin-booking - Booking plugin (integrates with payments for deposits)

License

MIT