PHPackages korozcolt/payments - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Payment Processing](/categories/payments) 4. / 5. korozcolt/payments ActiveLibrary[Payment Processing](/categories/payments) korozcolt/payments ================== A payment gateway package for Laravel supporting Wompi, MercadoPago, and ePayco. Designed for Colombian and Latin American markets. v2.0.1(3w ago)2205↓91%[1 issues](https://github.com/korozcolt/payments/issues)MITPHPPHP ^8.2 Since Jan 23Pushed 6mo agoCompare [ Source](https://github.com/korozcolt/payments)[ Packagist](https://packagist.org/packages/korozcolt/payments)[ Docs](https://github.com/korozcolt/payments)[ RSS](/packages/korozcolt-payments/feed)WikiDiscussions master Synced 1w ago READMEChangelog (1)Dependencies (20)Versions (4)Used By (0) Korozcolt Payments ================== [](#korozcolt-payments) [![Latest Version on Packagist](https://camo.githubusercontent.com/8c069c32118e9b4ea0b0865fdf238b5903e4d425fe77b12572766445a1e1dae9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6b6f726f7a636f6c742f7061796d656e74732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/korozcolt/payments)[![Total Downloads](https://camo.githubusercontent.com/82a5606bde85a6715ff230fd96437bb733a21a93e7a0f1478fc70820e84f569d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6b6f726f7a636f6c742f7061796d656e74732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/korozcolt/payments)[![License](https://camo.githubusercontent.com/e00d575bede665285f46e868b8d2c2bc8305232b0a260fdd1b62cff6dbfd63f3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6b6f726f7a636f6c742f7061796d656e74732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/korozcolt/payments) A unified payment gateway package for Laravel supporting **Wompi**, **MercadoPago**, and **ePayco**. Designed for Colombian and Latin American markets. Features -------- [](#features) - **Unified API** - Single interface for multiple payment providers - **Three Providers** - Wompi, MercadoPago, and ePayco out of the box - **Driver Architecture** - Easily extensible for custom providers - **Event-Driven** - Listen to payment events for business logic - **Webhook Handling** - Built-in webhook controller with signature verification - **Flexible Configuration** - Database or config-based credential management - **Laravel 10/11/12/13** - Full compatibility with recent Laravel versions Supported Providers ------------------- [](#supported-providers) ProviderCountryMethodsAutomated RefundsSubscriptionsPayouts**Wompi**ColombiaCards, PSE, Nequi, Bancolombia, EfectyCard only, pre-settlement `void`, full amount only — otherwise manualYes — via tokenized "payment sources" + this package's own schedulerYes — separate module/credentials, confirmed via official OpenAPI spec**MercadoPago**Latin AmericaCards, Bank Transfer, CashYes — full or partialYes — native engine, bills itself automaticallyNot available — no payouts API**ePayco**ColombiaCards, PSE, Efecty, BalotoNot implemented — always manual (see USAGE.md)Not implemented — unverified billing behavior (see USAGE.md)Yes — endpoints confirmed, auth mechanism unverified (see USAGE.md)Refund, subscription, and payout support genuinely differ per provider's own API — see [Reembolsos](USAGE.md#reembolsos-refunds), [Suscripciones](USAGE.md#suscripciones-recurring-payments), and [Payouts](USAGE.md#payouts-pagos-a-terceros) in USAGE.md before relying on `refund()`, `createSubscription()`, or `createPayout()`. Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 10, 11, 12, or 13 Installation ------------ [](#installation) ``` composer require korozcolt/payments ``` Publish the configuration: ``` php artisan vendor:publish --tag=payments-config ``` Run the migrations: ``` php artisan vendor:publish --tag=payments-migrations php artisan migrate ``` Quick Start ----------- [](#quick-start) ### 1. Configure Environment [](#1-configure-environment) ``` PAYMENTS_DEFAULT=wompi PAYMENTS_ENABLED=wompi,mercadopago,epayco WOMPI_PUBLIC_KEY=pub_test_xxx WOMPI_PRIVATE_KEY=prv_test_xxx WOMPI_INTEGRITY_KEY=test_integrity_xxx ``` ### 2. Create a Payment [](#2-create-a-payment) ``` use Korbytes\Payments\Facades\Payments; use Korbytes\Payments\DTOs\PaymentData; $paymentData = new PaymentData( referenceId: $order->id, amount: 150000, // Amount in cents (1,500.00 COP) currency: 'COP', customer: [ 'name' => 'John Doe', 'email' => 'john@example.com', ], returnUrl: 'https://yourapp.com/payment/complete', ); // Use default driver $result = Payments::charge($paymentData); // Or specify a driver $result = Payments::driver('wompi')->charge($paymentData); ``` ### 3. Handle the Result [](#3-handle-the-result) ``` if ($result->success) { return view('payment.widget', [ 'widgetUrl' => $result->widgetUrl, 'publicKey' => $result->publicKey, 'reference' => $result->reference, 'signature' => $result->signature, 'amount' => $result->amountInCents, ]); } ``` ### 4. Listen to Events [](#4-listen-to-events) ``` // In EventServiceProvider use Korbytes\Payments\Events\PaymentApproved; protected $listen = [ PaymentApproved::class => [ \App\Listeners\HandlePaymentApproved::class, ], ]; ``` ``` // app/Listeners/HandlePaymentApproved.php class HandlePaymentApproved { public function handle(PaymentApproved $event): void { $transaction = $event->transaction; // Update your order, send emails, etc. Order::where('id', $transaction->reference_id) ->update(['status' => 'paid']); } } ``` Documentation ------------- [](#documentation) - [Installation Guide](INSTALL.md) - Detailed installation instructions - [Usage Guide](USAGE.md) - Complete usage examples and patterns - [Changelog](CHANGELOG.md) - Version history Configuration ------------- [](#configuration) ### Environment Variables [](#environment-variables) ``` # General PAYMENTS_DEFAULT=wompi PAYMENTS_ENABLED=wompi,mercadopago,epayco PAYMENTS_USE_DATABASE=true PAYMENTS_RETURN_URL=https://yourapp.com/payment/complete PAYMENTS_WEBHOOK_URL=https://yourapp.com/payments/webhooks # Wompi WOMPI_SANDBOX=true WOMPI_PUBLIC_KEY=pub_test_xxx WOMPI_PRIVATE_KEY=prv_test_xxx WOMPI_INTEGRITY_KEY=test_integrity_xxx WOMPI_EVENTS_SECRET=test_events_xxx # MercadoPago MERCADOPAGO_SANDBOX=true MERCADOPAGO_ACCESS_TOKEN=TEST-xxx MERCADOPAGO_PUBLIC_KEY=TEST-xxx # ePayco EPAYCO_SANDBOX=true EPAYCO_PUBLIC_KEY=xxx EPAYCO_PRIVATE_KEY=xxx EPAYCO_P_CUST_ID=xxx EPAYCO_P_KEY=xxx ``` ### Webhook URLs [](#webhook-urls) Configure these in your payment provider dashboards: ProviderURLWompi`https://yourapp.com/payments/webhooks/wompi`MercadoPago`https://yourapp.com/payments/webhooks/mercadopago`ePayco`https://yourapp.com/payments/webhooks/epayco`Events ------ [](#events) EventDescription`PaymentCreated`Payment intent created`PaymentApproved`Payment approved by provider`PaymentRejected`Payment rejected/failed`PaymentRefunded`Payment successfully refunded via the provider's API (not dispatched for manual/unsupported refunds)`SubscriptionCreated`Customer subscribed to a plan`SubscriptionCancelled`Subscription cancelled`SubscriptionChargeSucceeded`A recurring cycle was charged successfully (scheduler-driven for Wompi, webhook-driven for MercadoPago)`SubscriptionChargeFailed`A recurring cycle charge failed — this package does no dunning/auto-cancellation, listen here for retry/notification logic`WebhookReceived`Webhook received from providerAPI Reference ------------- [](#api-reference) ### Facades [](#facades) ``` // Get a driver Payments::driver('wompi'); // Charge using default driver Payments::charge($paymentData); // Check availability Payments::isAvailable('wompi'); Payments::hasAvailableDriver(); // Get enabled drivers Payments::enabledDrivers(); // Get active gateways from database Payments::activeGateways(); // Extend with custom driver Payments::extend('custom', CustomDriver::class); ``` ### PaymentData DTO [](#paymentdata-dto) ``` $paymentData = new PaymentData( referenceId: string, // Your order/reference ID amount: int, // Amount in cents currency: string, // ISO 4217 code (default: COP) customer: array, // [name, email, phone?] returnUrl: ?string, // Redirect after payment webhookUrl: ?string, // Webhook notification URL description: ?string, // Payment description metadata: array, // Custom data items: array, // Line items ); ``` ### PaymentResult DTO [](#paymentresult-dto) ``` $result->success; // bool $result->transaction; // PaymentTransaction model $result->provider; // PaymentProvider enum $result->widgetUrl; // Widget script URL $result->publicKey; // Provider public key $result->amountInCents; // Amount $result->currency; // Currency code $result->reference; // Transaction reference $result->signature; // Payment signature $result->redirectUrl; // Redirect URL $result->extra; // Provider-specific data $result->errorCode; // Error code (if failed) $result->errorMessage; // Error message (if failed) ``` ### RefundResult DTO [](#refundresult-dto) ``` $result = Payments::driver($provider)->refund($transaction, amountInCents: null); // null = full refund $result->success; // bool $result->transaction; // PaymentTransaction model $result->refundedAmountInCents; // Amount actually refunded $result->providerRefundId; // Provider's refund ID $result->errorCode; // 'NOT_REFUNDABLE' | 'NO_PROVIDER_ID' | 'API_ERROR' | 'MANUAL_REFUND_REQUIRED' | 'REFUND_NOT_SUPPORTED' $result->errorMessage; // Explains why, and what to do manually if applicable ``` `REFUND_NOT_SUPPORTED` and `MANUAL_REFUND_REQUIRED` are normal, expected outcomes for Wompi and ePayco in many cases — not exceptions. See [Reembolsos in USAGE.md](USAGE.md#reembolsos-refunds) for exactly what each provider supports. ### Payouts (third-party payments) [](#payouts-third-party-payments) ``` use Korbytes\Payments\Facades\Payments; $driver = Payments::payoutDriver('wompi'); // throws PaymentException if unsupported (e.g. mercadopago) $beneficiary = $driver->registerBeneficiary($payoutBeneficiaryData)->beneficiary; $result = $driver->createPayout(new \Korbytes\Payments\DTOs\PayoutData( beneficiary: $beneficiary, referenceId: 'FACTURA-123', amount: 100000, )); $driver->queryPayoutStatus($result->payout); ``` Payouts use their own `PayoutDriverInterface` (not part of the main charge/refund/subscription contract) and entirely separate credentials from the payment gateway — see [Payouts in USAGE.md](USAGE.md#payouts-pagos-a-terceros). Extending --------- [](#extending) Create a custom driver: ``` use Korbytes\Payments\Drivers\AbstractDriver; use Korbytes\Payments\Contracts\PaymentDriverInterface; class CustomDriver extends AbstractDriver implements PaymentDriverInterface { public function getName(): string { return 'custom'; } // Implement other required methods... } // Register in a service provider Payments::extend('custom', CustomDriver::class); ``` Testing ------- [](#testing) ``` composer test ``` Security -------- [](#security) If you discover any security-related issues, please open an issue on the [GitHub repository](https://github.com/korozcolt/payments/issues). Credits ------- [](#credits) - [Korozcolt](https://github.com/korozcolt) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE) for more information. ### Health Score 38 — LowBetter than 83% of packages Maintenance69 Regular maintenance activity Popularity17 Limited adoption so far Community2 Small or concentrated contributor base Maturity50 Maturing project, gaining track record How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~91 days Total 3 Last Release 23d ago Major Versions v1.0.0 → v2.0.02026-07-25 ### Community Maintainers ![](https://www.gravatar.com/avatar/ae8fe3df56dd3599a06587d3c21edeb9ff5633d4c4ec20e2f9c7e6c876107bc1?d=identicon)[korozcolt](/maintainers/korozcolt) --- Tags laravelpaymentsmercadopagocheckoutpayment gatewayepaycoWompicolombiapse ### Code Quality TestsPest Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/korozcolt-payments/health.svg) ``` [![Health](https://phpackages.com/badges/korozcolt-payments/health.svg)](https://phpackages.com/packages/korozcolt-payments) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3345.4M354](/packages/psalm-plugin-laravel)[api-platform/laravel API Platform support for Laravel 58190.1k21](/packages/api-platform-laravel)[laravel/cashier Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services. 2.6k31.8M160](/packages/laravel-cashier)[laravel/mcp Rapidly build MCP servers for your Laravel applications. 79227.1M227](/packages/laravel-mcp)[fleetbase/core-api Core Framework and Resources for Fleetbase API 1239.7k25](/packages/fleetbase-core-api)[pressbooks/pressbooks Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS. 45844.8k1](/packages/pressbooks-pressbooks) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)