korozcolt/payments

A payment gateway package for Laravel supporting Wompi, MercadoPago, and ePayco. Designed for Colombian and Latin American markets.

v1.0.0 2026-01-23 20:22 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^10.0|^11.0|^12.0
• illuminate/database: ^10.0|^11.0|^12.0
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/routing: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0
• mercadopago/dx-php: ^3.0

Requires (Dev)

• laravel/pint: ^1.0
• orchestra/testbench: ^8.0|^9.0|^10.0
• pestphp/pest: ^2.0|^3.0
• pestphp/pest-plugin-laravel: ^2.0|^3.0

MIT

• Korozcolt

• checkout
• payments
• laravel
• mercadopago
• colombia
• payment-gateway
• pse
• epayco
• Wompi

README

A unified payment gateway package for Laravel supporting Wompi, MercadoPago, and ePayco. Designed for Colombian and Latin American markets.

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 - Full compatibility with recent Laravel versions

Supported Providers

Provider	Country	Methods
Wompi	Colombia	Cards, PSE, Nequi, Bancolombia, Efecty
MercadoPago	Latin America	Cards, Bank Transfer, Cash
ePayco	Colombia	Cards, PSE, Efecty, Baloto

Requirements

• PHP 8.2+
• Laravel 10, 11, or 12

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

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

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' => '[e-mail]',
    ],
    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

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

// 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

• Installation Guide - Detailed installation instructions
• Usage Guide - Complete usage examples and patterns
• Changelog - Version history

Configuration

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

Configure these in your payment provider dashboards:

Provider	URL
Wompi	https://yourapp.com/payments/webhooks/wompi
MercadoPago	https://yourapp.com/payments/webhooks/mercadopago
ePayco	https://yourapp.com/payments/webhooks/epayco

Events

Event	Description
PaymentCreated	Payment intent created
PaymentApproved	Payment approved by provider
PaymentRejected	Payment rejected/failed
WebhookReceived	Webhook received from provider

API Reference

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 = 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

$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)

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

composer test

Security

If you discover any security-related issues, please open an issue on the GitHub repository.

Credits

• Korozcolt
• All Contributors

License

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