flowcoders / maestro
Unified payment gateway for Laravel - Write once, use with any payment provider (MercadoPago, Stripe, and more)
Fund package maintenance!
flowcoders
Requires
- php: ^8.3
- illuminate/contracts: ^10.0||^11.0||^12.0
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- larastan/larastan: ^2.9||^3.0
- laravel/pint: ^1.14
- nunomaduro/collision: ^8.1.1||^7.10.0
- orchestra/testbench: ^10.0.0||^9.0.0||^8.22.0
- pestphp/pest: ^2.0||^3.0
- pestphp/pest-plugin-arch: ^2.5||^3.0
- pestphp/pest-plugin-laravel: ^2.0||^3.0
- phpstan/extension-installer: ^1.3||^2.0
- phpstan/phpstan-deprecation-rules: ^1.1||^2.0
- phpstan/phpstan-phpunit: ^1.3||^2.0
This package is not auto-updated.
Last update: 2025-09-26 16:14:25 UTC
README
Stop rewriting payment code every time you switch payment providers.
Maestro provides a single, consistent API for all your payment needs. Whether you're using MercadoPago today and want to add Stripe tomorrow, or need to switch providers entirely - your code stays the same.
Why Maestro?
The Problem: Every payment provider has different APIs, data formats, and integration patterns. Switching providers means rewriting all your payment logic.
The Solution: Write your payment code once, use it with any provider.
// This same code works with MercadoPago, Stripe, or any other provider $money = new Money(10000, Currency::BRL); // R$ 100.00 in cents $pix = new Pix(expiresAt: 60); // 1 hour expiration $payment = Maestro::createPayment(new PaymentRequest( money: $money, paymentMethod: $pix, description: 'Product purchase', customer: new Customer(/* ... */), ));
What's Included
- โ MercadoPago - Full support including PIX
- ๐ More providers coming - Stripe, Adyen, PagSeguro
- ๐ก๏ธ Type-safe - Full PHP 8.3+ type declarations
- ๐งช Battle-tested - Comprehensive test coverage
Installation
composer require flowcoders/maestro
Quick Setup
- Add your credentials to
.env
:
MERCADOPAGO_ACCESS_TOKEN=TEST-your_token_here
- Start processing payments:
use Flowcoders\Maestro\Facades\Maestro; use Flowcoders\Maestro\ValueObjects\Money; use Flowcoders\Maestro\ValueObjects\PaymentMethod\Pix; $payment = Maestro::createPayment(/* ... */);
That's it! No config files, no complex setup.
Usage Examples
Create a Payment
use Flowcoders\Maestro\Facades\Maestro; use Flowcoders\Maestro\DTOs\PaymentRequest; use Flowcoders\Maestro\DTOs\Customer; use Flowcoders\Maestro\ValueObjects\Money; use Flowcoders\Maestro\ValueObjects\Email; use Flowcoders\Maestro\ValueObjects\PaymentMethod\Pix; use Flowcoders\Maestro\Enums\Currency; // Create payment components $money = new Money(10000, Currency::BRL); // R$ 100.00 in cents $pix = new Pix(expiresAt: 60); // Expires in 1 hour $customer = new Customer( firstName: 'John', lastName: 'Doe', email: new Email('customer@example.com') ); // Create the payment $payment = Maestro::createPayment(new PaymentRequest( money: $money, paymentMethod: $pix, description: 'Product purchase', customer: $customer )); // Get payment details echo $payment->id; // Payment ID from provider echo $payment->status->value; // 'pending', 'approved', etc.
All Operations
// Create payment $payment = Maestro::createPayment($paymentRequest); // Get payment status $payment = Maestro::getPayment('payment_id'); // Cancel payment $payment = Maestro::cancelPayment('payment_id'); // Refund payment (full or partial) $refundMoney = new Money(5000, Currency::BRL); // Partial refund $payment = Maestro::refundPayment(new RefundRequest( paymentId: 'payment_id', money: $refundMoney, // Optional: leave null for full refund reason: 'Customer request' ));
๐ฐ Money Handling
Use the Money value object with amounts in cents:
// โ Correct $money = new Money(10000, Currency::BRL); // R$ 100.00 // โ Wrong amount: 100.00 // This field doesn't exist
Maestro automatically converts to each provider's expected format.
Need More Examples?
Check out examples/basic-usage.php
for a complete working example with all features.
Contributing
Contributions are welcome! Please see our contributing guide.
Testing
composer test
Security
For security vulnerabilities, please email the maintainer directly instead of using the issue tracker.
Credits
- Paulo Guerra - Creator & maintainer
License
MIT License. See LICENSE.md for details.