Download the PHP package ideacrafters/eloquent-payable without Composer

Eloquent Payable

A Laravel package that enables any Eloquent model to accept payments by adding a simple trait. Perfect for invoices, products, subscriptions, fees, donations, and any other payment scenarios.

📋 Upgrading? If you're upgrading from version 1.x, please check the Migration Guide for breaking changes and required updates.
📝 Changelog: See CHANGELOG.md for a complete list of changes in version 2.0.0.

Features

• 🚀 One-line integration - Add payment capabilities to any model with a single trait
• 💳 Multiple processors - Stripe, offline payments, and free items out of the box
• 🔄 Swappable processors - Switch payment providers without changing your code
• 📊 Complete payment history - Track all payments with detailed metadata
• 🎯 Flexible scenarios - Works for products, invoices, subscriptions, fees, donations
• 🔒 Secure - Webhook signature verification and PCI compliance through tokenization
• 📈 Event-driven - Comprehensive event system for payment lifecycle
• ⚡ Performance optimized - Efficient queries with proper indexing
• 🧪 Well tested - Comprehensive test suite included

Installation

You can install the package via Composer:

Publish the configuration file:

Run the migrations:

Quick Start

1. Make your model payable

2. Add payments to your user model

3. Process payments

Facade Usage

The package includes a powerful Facade for easy access to payment operations:

Configuration

The package configuration is published to config/payable.php. Here are the key options:

Redirect-Based Payments

The package now supports redirect-based payments for processors like Stripe Checkout:

Redirect URLs

The package provides flexible redirect URL handling:

• Custom URLs: Pass success_url, cancel_url, failure_url in options
• Default URLs: Uses package's built-in redirect handlers
• Metadata URLs: Store URLs in payment metadata for later use

Redirect Controller

The package includes a RedirectController that handles:

• Payment completion verification
• Automatic payment status updates
• Custom redirect URL support
• Error handling and logging

Payment Processors

Stripe Processor

The Stripe processor handles online payments with full webhook support:

Environment Variables:

Offline Processor

For manual payments like cash, checks, or bank transfers:

No Processor

For free items or services:

Payment Scenarios

E-commerce Products

Service Invoices

Donations

Subscription Fees

Payment Relationships

Payable Models

Payer Models

Events

The package fires events throughout the payment lifecycle:

Deprecated Events:

The following events are deprecated and will be removed in a future version. Use the main events with flags instead:

• OfflinePaymentCreated - Use PaymentCreated with isOffline flag instead
• OfflinePaymentConfirmed - Use PaymentCompleted instead (offline payments fire PaymentCompleted when marked as paid)

Webhooks

Stripe Webhooks

The package automatically handles Stripe webhooks at /payable/webhooks/stripe:

Custom Webhooks

Callbacks

The package provides callback URLs for payment success, cancellation, and failure:

• Success: /payable/callback/success?payment={id}
• Cancel: /payable/callback/cancel?payment={id}
• Failed: /payable/callback/failed?payment={id}

Facade API Reference

The Payable Facade provides a comprehensive API for all payment operations:

Payment Processing

• Payable::process($payable, $payer, $amount, $options) - Process a payment
• Payable::processOffline($payable, $payer, $amount, $options) - Create offline payment
• Payable::refund($payment, $amount) - Refund a payment

Payment Management

• Payable::find($id) - Find payment by ID
• Payable::markAsPaid($payment, $paidAt) - Mark as paid
• Payable::markAsFailed($payment, $reason) - Mark as failed
• Payable::markAsPending($payment) - Mark as pending

Payment Queries

• Payable::getPaymentsFor($payable) - Get payments for an item
• Payable::getPaymentsBy($payer) - Get payments by a payer
• Payable::getTotalPaidBy($payer) - Get total paid by payer
• Payable::getTotalPaidFor($payable) - Get total paid for item
• Payable::hasPaidFor($payable, $payer) - Check if payer paid for item
• Payable::getLatestPaymentFor($payable, $payer) - Get latest payment

Payment Collections

• Payable::getCompletedPayments() - All completed payments
• Payable::getPendingPayments() - All pending payments
• Payable::getFailedPayments() - All failed payments
• Payable::getOfflinePayments() - All offline payments
• Payable::getPaymentsToday() - Today's payments
• Payable::getPaymentsThisMonth() - This month's payments

Statistics & Analytics

• Payable::getPaymentStats() - Payment statistics
• Payable::getProcessorStats() - Processor statistics
• Payable::getMetrics() - All metrics
• Payable::getHealthCheck() - System health check

Configuration & Management

• Payable::getConfiguration() - Get all configuration
• Payable::getSupportedCurrencies() - Supported currencies
• Payable::getDefaultCurrency() - Default currency
• Payable::getProcessorNames() - Available processors
• Payable::isProcessorSupported($name) - Check processor support
• Payable::setDefaultProcessor($name) - Set default processor

Utility Methods

• Payable::getPaymentUrls($payment) - Get callback URLs
• Payable::getWebhookUrls() - Get webhook URLs
• Payable::getCallbackUrls() - Get callback URLs
• Payable::clearCache() - Clear cached data
• Payable::warmCache() - Warm up cache

Logging

• Payable::debug($message, $context) - Debug log
• Payable::info($message, $context) - Info log
• Payable::warning($message, $context) - Warning log
• Payable::error($message, $context) - Error log
• Payable::critical($message, $context) - Critical log

Advanced Usage

Custom Payment Processors

Create your own payment processor:

Register your processor in the config:

Custom Payment Logic

Override methods in your payable models:

Payment Queries

Use the built-in scopes for efficient queries:

Testing

The package includes comprehensive tests. Run them with:

Testing Payments

Security

• PCI Compliance: The package never handles card data directly
• Webhook Verification: All webhooks are signature verified
• SQL Injection Protection: Uses Eloquent ORM for all database operations
• CSRF Protection: Web routes are protected by default
• Rate Limiting: Webhook endpoints are rate limited

Performance

• Optimized Queries: Uses eager loading and proper indexing
• Efficient Webhooks: Processes webhooks in under 200ms
• Scalable: Supports high-volume payments (1000+ per minute)
• Memory Efficient: Minimal memory footprint per request

Requirements

• PHP 8.0+
• Laravel 8.0+
• MySQL 5.7+, PostgreSQL 10+, or SQLite 3.8.8+

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Ideacrafters
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Support

If you discover any issues or have questions, please open an issue on GitHub or contact us at [email protected].

Made with ❤️ by Ideacrafters