event-tickets-mail-in-payment/README.md

# Event Tickets - Mail-In Payment Gateway

A complementary WordPress plugin that adds a mail-in payment gateway for Event Tickets Commerce, allowing customers to pay by mailing checks.

## Description

This plugin extends the Event Tickets plugin by adding a "Mail-In Payment (Check)" gateway that allows customers to reserve tickets and pay by mailing a check. It provides comprehensive order management features for administrators to track and process check payments.

## Features

- **Check Payment Gateway**: Seamlessly integrates with Event Tickets Commerce
- **Order Management**: Admin interface to track pending check payments
- **Email Notifications**: Automated emails for payment instructions, confirmations, and cancellations
- **Customizable Settings**: Configure mailing address, payment instructions, and reservation periods
- **Order Tracking**: Track check received status, bounce handling, and order notes
- **Auto-Cancellation**: Optional automatic cancellation of expired orders
- **Template System**: Customizable checkout and email templates

## Requirements

- WordPress 6.6 or higher
- PHP 7.4 or higher
- Event Tickets plugin (with Commerce module)
- The Events Calendar plugin (recommended)

## Installation

1. Download the plugin files
2. Upload the `event-tickets-mail-in-payment` folder to `/wp-content/plugins/`
3. Activate the plugin through the 'Plugins' menu in WordPress
4. Configure the gateway settings under **Tickets > Settings > Payments**

## Configuration

### Basic Setup

1. Navigate to **Tickets > Settings > Payments**
2. Find the "Mail-In Payment (Check) Settings" section
3. Configure the required settings:
   - **Enable Mail-In Payments**: Check to activate the gateway
   - **Make Check Payable To**: Organization or person name for checks
   - **Mailing Address**: Complete address where checks should be sent
   - **Payment Instructions**: Custom instructions for customers

### Advanced Settings

- **Payment Method Title**: Customize the gateway name shown to customers
- **Payment Method Description**: Brief description shown during checkout
- **Reservation Period**: Number of days to hold tickets while awaiting payment
- **Auto-Cancel Expired Orders**: Automatically cancel orders after reservation period

## Order Management

### Admin Interface

Access mail-in payment management through:
- **Tickets > Orders > Mail-In Payments** - Dedicated management page
- Individual order edit screens include mail-in payment details

### Order Processing

1. **Pending Orders**: Orders awaiting check payment appear in the management interface
2. **Mark as Received**: When a check arrives, mark it as received with optional notes
3. **Mark as Bounced**: Handle returned/bounced checks with reason tracking
4. **Automatic Emails**: System sends confirmation emails when status changes

### Order Statuses

- **Pending/Approved**: Order created, awaiting check payment
- **Completed**: Check received and processed
- **Denied**: Check bounced or order manually cancelled

## Templates

### Customization

Templates can be overridden by copying them to your theme:

```
wp-content/themes/[your-theme]/event-tickets-mail-in/
├── checkout/
│   └── mail-in-form.php
├── emails/
│   ├── payment-instructions.php
│   ├── payment-confirmation.php
│   └── order-cancelled.php
└── admin/
    ├── mail-in-orders.php
    └── order-meta-box.php
```

### Available Templates

- **Checkout Form**: `checkout/mail-in-form.php` - Payment method display during checkout
- **Email Templates**: Complete HTML email templates for all notifications
- **Admin Templates**: Management interface templates

## Hooks and Filters

### Actions

```php
// Triggered when a check is marked as received
do_action( 'et_mail_in_check_received', $order_id, $notes );

// Triggered when a check is marked as bounced
do_action( 'et_mail_in_check_bounced', $order_id, $reason );

// Daily cleanup of expired orders
do_action( 'et_mail_in_cleanup_expired_orders' );
```

### Filters

```php
// Customize payment instructions
add_filter( 'et_mail_in_payment_instructions', function( $instructions, $order ) {
    return $instructions;
}, 10, 2 );

// Modify email content
add_filter( 'et_mail_in_email_content', function( $content, $template, $order ) {
    return $content;
}, 10, 3 );

// Customize reservation period per order
add_filter( 'et_mail_in_reservation_days', function( $days, $order ) {
    return $days;
}, 10, 2 );
```

## Email System

### Automated Emails

1. **Payment Instructions**: Sent when order is created
2. **Payment Confirmation**: Sent when check is marked as received
3. **Order Cancellation**: Sent when order is cancelled or expires

### Email Customization

- HTML templates with responsive design
- Includes order details, payment instructions, and mailing address
- Uses WordPress mail system with customizable headers

## Security Features

- **Nonce Verification**: All admin actions are protected with WordPress nonces
- **Capability Checks**: Admin functions require appropriate user permissions
- **Data Sanitization**: All user inputs are properly sanitized
- **Order Validation**: Prevents unauthorized access to order data

## Development

### File Structure

```
event-tickets-mail-in-payment/
├── event-tickets-mail-in-payment.php  # Main plugin file
├── src/                               # Core classes
│   ├── Gateway.php                   # Payment gateway implementation
│   ├── Order.php                     # Order management
│   ├── Settings.php                  # Configuration handling
│   ├── Provider.php                  # Service provider
│   └── Hooks.php                     # WordPress hooks
├── templates/                         # Template files
│   ├── checkout/                     # Frontend templates
│   ├── emails/                       # Email templates
│   └── admin/                        # Admin interface templates
└── README.md                         # Documentation
```

### Extending the Plugin

The plugin is built with extensibility in mind:

- PSR-4 autoloading with namespace `ET_Mail_In_Payment`
- Service provider pattern for modular functionality
- Hook system for customization
- Template override system

## Troubleshooting

### Common Issues

1. **Gateway Not Appearing**: Ensure Event Tickets plugin is active and Commerce module is enabled
2. **Settings Not Saving**: Check file permissions and WordPress error logs
3. **Emails Not Sending**: Verify WordPress mail configuration
4. **Template Issues**: Clear any caching plugins after template changes

### Debug Mode

Enable WordPress debug mode to see detailed error messages:

```php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
```

## Support

For support and questions:

1. Check the plugin settings and this documentation
2. Review WordPress error logs for any issues
3. Ensure all requirements are met
4. Contact the plugin developer for technical support

## License

This plugin is licensed under the GPL v2 or later.

## Changelog

### 1.0.0
- Initial release
- Mail-in payment gateway implementation
- Order management interface
- Email notification system
- Template system
- Settings configuration