Download the PHP package digitaldev-lx/laravel-eupago without Composer

Laravel EuPago

A comprehensive Laravel package for integrating with the EuPago payment gateway API. Support for Multibanco, MB Way, Credit Card, Google Pay, Apple Pay, and Payouts management.

Requirements

Installation

Publish the migration

Run the migration

Publish the configuration file (optional)

Publish the translations files (optional)

Configuration

Environment Variables

Add the following to your .env file:

There are two environments available: "test" and "prod". Use the "test" environment during development and switch to "prod" when your application is ready for production.

Callback Security

The callback endpoint (GET /eupago/callback) is the trust boundary that confirms payments, so it is hardened as follows:

• API key authentication — the chave_api parameter is compared against EUPAGO_API_KEY in constant time (hash_equals). Invalid callbacks are rejected with an HTTP 422 and never reveal which field failed.
• No secret leakage — the API key is never logged (only a redacted summary is, when EUPAGO_LOG_CALLBACKS=true) and is stripped from the CallbackReceived event payload.
• Atomic confirmation — payments are confirmed inside a locked transaction, so concurrent callbacks for the same reference cannot fire the "paid" event twice.
• Rate limiting — the route is throttled to 60 requests/minute per IP.
• Optional IP allowlist — set EUPAGO_ALLOWED_IPS to the EuPago callback source IPs to reject any other origin. Leave it empty to accept all (default).

Payment Methods

Multibanco (MB) References

Usage

Response format:

Using the Trait

Callback

The package handles callbacks automatically, updating the payment state and triggering events.

Endpoint: GET /eupago/callback Payment Method Code: PC:PT

MB Way References

Usage

Using the Trait

Callback

Endpoint: GET /eupago/callback Payment Method Code: MW:PT

Credit Card

Single Payment

Maximum: €3,999 per transaction Callback Code: CC:PT

Recurring Payments (Subscriptions)

Step 1: Create Authorization

Step 2: Execute Recurring Payment

Using the Trait

Google Pay

Maximum: €99,999 per transaction Callback Code: GP:PT

Using the Trait

Apple Pay

Callback Code: AP:PT

Using the Trait

Payouts Management

List Payouts

Retrieve all payouts for a specific date range using OAuth Bearer Token authentication.

List Payout Transactions

Retrieve all transaction details within a date range.

Note: For single-day queries, use the same date for both start_date and end_date.

Callback Parameters

All payment callbacks receive the following parameters:

Events

The package dispatches events throughout the payment lifecycle.

Reference Creation Events

• MBReferenceCreated / MBReferenceCreationFailed
• MBWayReferenceCreated / MBWayReferenceCreationFailed
• CreditCardReferenceCreated / CreditCardReferenceCreationFailed
• CreditCardRecurrenceAuthorizationCreated / CreditCardRecurrenceAuthorizationCreationFailed
• CreditCardRecurringPaymentCreated / CreditCardRecurringPaymentCreationFailed
• GooglePayReferenceCreated / GooglePayReferenceCreationFailed
• ApplePayReferenceCreated / ApplePayReferenceCreationFailed

Payment Events

• MBReferencePaid
• MBWayReferencePaid
• CreditCardReferencePaid
• GooglePayReferencePaid
• ApplePayReferencePaid

Expiration Events

• MBReferenceExpired
• MBWayReferenceExpired

Callback Events

• CallbackReceived - Dispatched for every valid callback. The payload excludes the API key and channel.
• InvalidCallbackReceived - Dispatched when a callback fails validation (wrong API key/channel, unknown payment method, malformed data). Carries the validation errors and a redacted callbackData (the API key and channel are excluded).

Invalid callbacks are rejected with a generic HTTP 422 response (no field-level detail), while listeners can still inspect the failure through InvalidCallbackReceived.

Listening to Events

Auto-discovery (recommended):

Create a listener class in app/Listeners/ — Laravel automatically discovers it via the type-hinted handle() method:

No manual registration needed. Laravel scans app/Listeners/ automatically.

Manual registration:

Register listeners in your app/Providers/AppServiceProvider.php:

Closure listeners:

Commands

Check Expired References

Check for expired payment references and dispatch expiration events:

This command finds all MB references where end_date has passed and state is 0 (unpaid), then dispatches MBReferenceExpired event for each.

Scheduling:

Laravel 11 & 12:

Add to your routes/console.php:

Laravel 10:

Add to your app/Console/Kernel.php:

Testing

The package includes comprehensive test coverage using Pest PHP.

Running Tests

Code Style

Static Analysis

Using Factories in Tests

Contributing

Please see CONTRIBUTING.md for details on how to contribute to this project.

Changelog

Please see CHANGELOG.md for details on recent changes.

License

digitaldev-lx/laravel-eupago is open-sourced software licensed under the MIT license.

About DigitalDev

DigitalDev is a digital transformation agency based in Lisbon, Portugal. We specialize in transforming ideas into digital solutions that drive business growth online.

With expertise in custom web development, system integration, DevOps, AI implementation, and advanced search systems, we help businesses scale beyond generic templates with practical, data-driven solutions. Our tech stack includes Laravel, Livewire, React, and modern cloud infrastructure.

Contact: [email protected] | +351 961 546 227