platform-codebase/@packages/@plugins/README.md

# @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

```bash
pnpm add @lilith/plugin-payment
```

## Usage

### Payment Methods

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

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

  // ...
}
```

### Creating Payment Intents

```tsx
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

```tsx
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

```bash
# 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