> LOADING LARAVEL-EUPAGO v3.2...

Laravel EuPago

Integracao completa com o gateway de pagamentos EuPago para Laravel. Multibanco, MB Way, cartoes de credito, wallets digitais e payouts.

Ver no GitHub

Overview

O Laravel EuPago e um pacote completo para integrar a sua aplicacao Laravel com o gateway de pagamentos EuPago, um dos principais processadores de pagamentos em Portugal. O pacote oferece classes dedicadas para cada metodo de pagamento, traits Eloquent para associar referencias a models, e um sistema de eventos robusto para acompanhar todo o ciclo de vida das transacoes.

PHP 8.4+ Laravel 11-13 MIT License Pest Tested Larastan Level 6

Download Postman Collection

Compatibilidade de versoes

Release	PHP	Laravel
3.0.0	>= 8.4	11, 12, 13
2.3.0	8.3, 8.4	11, 12
2.2.0	>= 8.3	11
2.1.0	>= 8.1	10

Metodos de pagamento suportados

Multibanco -- referencias com callback automatico e verificacao de expiracao
MB Way -- pagamento movel instantaneo por telefone
Cartoes de Credito -- pagamentos unicos e subscricoes recorrentes
Google Pay -- wallet digital com dados do cliente
Apple Pay -- wallet digital Apple
Payouts -- listagem de pagamentos e transacoes

Instalacao

Instale o pacote via Composer e publique as migrations necessarias.

Instalacao

bash

composer require digitaldev-lx/laravel-eupago

Publicar migrations e migrar

bash

php artisan vendor:publish --provider=DigitaldevLx\\LaravelEupago\\Providers\\EuPagoServiceProvider --tag=migrations
php artisan migrate

Opcionalmente, publique o ficheiro de configuracao e as traducoes:

Opcional

bash

php artisan vendor:publish --provider=DigitaldevLx\\LaravelEupago\\Providers\\EuPagoServiceProvider --tag=config
php artisan vendor:publish --provider=DigitaldevLx\\LaravelEupago\\Providers\\EuPagoServiceProvider --tag=translations

Configuracao

Adicione as seguintes variaveis ao ficheiro .env:

.env

bash

EUPAGO_ENV=test          # ou 'prod'
EUPAGO_API_KEY=your_api_key
EUPAGO_CHANNEL=your_channel

# Opcional — hardening do callback
EUPAGO_ALLOWED_IPS=        # IPs da EuPago separados por virgula; vazio = aceita todos
EUPAGO_LOG_CALLBACKS=true  # regista resumo redactado dos callbacks (nunca a API key)

Variaveis de ambiente

Variavel	Descricao	Valores
EUPAGO_ENV	Ambiente da API	test / prod
EUPAGO_API_KEY	Chave de autenticacao da API EuPago	--
EUPAGO_CHANNEL	Identificador do canal de pagamento	--
EUPAGO_ALLOWED_IPS	IPs da EuPago permitidos (separados por virgula); vazio aceita todos	opcional
EUPAGO_LOG_CALLBACKS	Registar resumo redactado dos callbacks (nunca a API key)	true / false

Seguranca dos callbacks

O endpoint de callback GET /eupago/callback e a fronteira de confianca que confirma pagamentos. O pacote implementa um conjunto de medidas de proteccao:

Autenticacao por API key — o parametro chave_api e comparado contra EUPAGO_API_KEY em tempo constante (hash_equals). Callbacks invalidos sao rejeitados com HTTP 422 sem revelar qual campo falhou.
Sem fuga de segredos — a API key nunca e registada nos logs. Quando EUPAGO_LOG_CALLBACKS=true, apenas um resumo redactado e persistido. O payload do evento CallbackReceived exclui a API key e o canal.
Confirmacao atomica — os pagamentos sao confirmados dentro de uma transacao com lock, impedindo que callbacks concorrentes para a mesma referencia disparem o evento "paid" duas vezes.
Rate limiting — a rota e limitada a 60 pedidos por minuto por IP.
Allowlist de IPs opcional — configure EUPAGO_ALLOWED_IPS com os IPs de origem da EuPago para rejeitar qualquer outra origem. Deixe vazio para aceitar todos (comportamento por defeito).

Multibanco

Gere referencias Multibanco com callback automatico quando o pagamento e efetuado. Os callbacks sao recebidos automaticamente em GET /eupago/callback.

Criar referencia Multibanco

php

use DigitaldevLx\LaravelEupago\MB\MB;

$order = Order::find(1);

$mb = new MB(
    $order->value,              // float: valor do pagamento
    $order->id,                 // string: identificador externo
    $order->date,               // string: data inicio (Y-m-d)
    $order->payment_limit_date, // string: data limite (Y-m-d)
    $order->value,              // float: valor minimo
    $order->value,              // float: valor maximo
    0                           // bool: permitir pagamentos duplicados
);

try {
    $mbReferenceData = $mb->create();

    if ($mb->hasErrors()) {
        // tratar erros
    }

    $order->mbReferences()->create($mbReferenceData);
} catch (\Exception $e) {
    // tratar excepcao
}

Trait Mbable

Adicione a trait ao model para associar referencias Multibanco:

Trait Mbable

php

use DigitaldevLx\LaravelEupago\Traits\Mbable;

class Order extends Model
{
    use Mbable;
}

$order = Order::find(1);
$mbReferences = $order->mbReferences;

MB Way

Pagamento movel instantaneo. O utilizador recebe uma notificacao na app MB Way e confirma com PIN. O callback e recebido com o codigo MW:PT.

Criar referencia MB Way

php

use DigitaldevLx\LaravelEupago\MBWay\MBWay;

$order = Order::find(1);

$mbway = new MBWay(
    $order->value,      // float: valor do pagamento
    $order->id,         // int: identificador externo
    $customer->phone,   // string: numero de telefone
    'Pagamento da encomenda' // string|null: descricao opcional
);

try {
    $mbwayReferenceData = $mbway->create();

    if ($mbway->hasErrors()) {
        // tratar erros
    }

    $order->mbwayReferences()->create($mbwayReferenceData);
} catch (\Exception $e) {
    // tratar excepcao
}

Trait Mbwayable

php

use DigitaldevLx\LaravelEupago\Traits\Mbwayable;

class Order extends Model
{
    use Mbwayable;
}

$order->mbwayReferences;

Cartoes de Credito

Pagamentos unicos com cartao de credito (maximo de 3.999 EUR por transacao) e subscricoes recorrentes com autorizacao previa. Callback com codigo CC:PT.

Pagamento unico

Cartao de Credito - Pagamento unico

php

use DigitaldevLx\LaravelEupago\CreditCard\CreditCard;

$creditCard = new CreditCard(
    150.00,                            // float: valor
    'ORDER-456',                       // string: identificador
    'https://example.com/success',     // string: URL sucesso
    'https://example.com/fail',        // string: URL falha
    'https://example.com/back',        // string: URL voltar
    'cliente@example.com',             // string: email do cliente (obrigatorio)
    'PT',                              // string: idioma (PT, EN, FR, ES)
    'EUR',                             // string: moeda
    true,                              // bool: notificar cliente
    60                                 // int|null: minutos para expirar
);

try {
    $result = $creditCard->create();

    if ($result['success']) {
        // Redirecionar para $result['redirect_url']
        // Guardar $result['reference'] e $result['transaction_id']
    }
} catch (\Exception $e) {
    // tratar excepcao
}

Subscricao recorrente

As subscricoes requerem dois passos: criar a autorizacao e depois executar pagamentos recorrentes.

Passo 1 - Criar autorizacao

php

use DigitaldevLx\LaravelEupago\CreditCard\CreditCardRecurrence;

$recurrence = new CreditCardRecurrence(
    'SUBSCRIPTION-123',                // string: identificador
);

$result = $recurrence->create();

if ($result['success']) {
    // Redirecionar para $result['redirect_url'] para autorizar a subscricao
    // Guardar $result['subscription_id']
}

Passo 2 - Executar pagamento recorrente

php

use DigitaldevLx\LaravelEupago\CreditCard\CreditCardRecurringPayment;

$payment = new CreditCardRecurringPayment(
    'subscription-id-da-autorizacao',  // string: subscription ID
    50.00,                             // float: valor
    'PAYMENT-789',                     // string: identificador
    'EUR',                             // string: moeda
    'cliente@example.com',             // string|null: email
    true                               // bool: notificar cliente
);

$result = $payment->create();

if ($result['success']) {
    // Pagamento processado
}

Traits para Eloquent

php

use DigitaldevLx\LaravelEupago\Traits\Creditcardable;
use DigitaldevLx\LaravelEupago\Traits\Creditcardrecurrable;

class Order extends Model
{
    use Creditcardable;
}

class Subscription extends Model
{
    use Creditcardrecurrable;
}

Google Pay e Apple Pay

Aceite pagamentos via wallets digitais. Google Pay suporta transacoes ate 99.999 EUR. Ambos recebem callbacks com codigos GP:PT e AP:PT.

Google Pay

php

use DigitaldevLx\LaravelEupago\GooglePay\GooglePay;

$googlePay = new GooglePay(
    150.00,                            // float: valor
    'ORDER-456',                       // string: identificador
    'https://example.com/success',     // string: URL sucesso
    'https://example.com/fail',        // string: URL falha
    'https://example.com/back',        // string: URL voltar
    'PT',                              // string: idioma
    'EUR',                             // string: moeda
    'cliente@example.com',             // string|null: email
    'John',                            // string|null: primeiro nome
    'Doe',                             // string|null: apelido
    'PT',                              // string|null: codigo pais
    true,                              // bool: notificar cliente
    60                                 // int|null: minutos para expirar
);

$result = $googlePay->create();

if ($result['success']) {
    return redirect($result['redirect_url']);
}

Apple Pay

php

use DigitaldevLx\LaravelEupago\ApplePay\ApplePay;

$applePay = new ApplePay(
    150.00,                            // float: valor
    'ORDER-456',                       // string: identificador
    'https://example.com/success',     // string: URL sucesso
    'https://example.com/fail',        // string: URL falha
    'https://example.com/back',        // string: URL voltar
    'PT',                              // string: idioma
    'EUR',                             // string: moeda
    'cliente@example.com',             // string|null: email
    'John',                            // string|null: primeiro nome
    'Doe',                             // string|null: apelido
    'PT',                              // string|null: codigo pais
    true,                              // bool: notificar cliente
    60                                 // int|null: minutos para expirar
);

$result = $applePay->create();

if ($result['success']) {
    return redirect($result['redirect_url']);
}

Traits para Eloquent

php

use DigitaldevLx\LaravelEupago\Traits\Googlepayable;
use DigitaldevLx\LaravelEupago\Traits\Applepayable;

class Order extends Model
{
    use Googlepayable, Applepayable;
}

$order->googlePayReferences;
$order->applePayReferences;

Payouts

Consulte pagamentos e transacoes realizados atraves da API de payouts. Requer autenticacao via OAuth Bearer Token.

Listar payouts

php

use DigitaldevLx\LaravelEupago\Payouts\Payout;

$payout = new Payout(
    '2024-01-01',          // string: data inicio (yyyy-mm-dd)
    '2024-01-31',          // string: data fim (yyyy-mm-dd)
    'your-bearer-token'    // string: OAuth Bearer Token
);

$result = $payout->list();

if ($result['success']) {
    foreach ($result['payouts'] as $payout) {
        // processar dados do payout
    }
}

Listar transacoes

php

use DigitaldevLx\LaravelEupago\Payouts\PayoutTransaction;

$transactions = new PayoutTransaction(
    '2024-01-01',          // string: data inicio
    '2024-01-31',          // string: data fim
    'your-bearer-token'    // string: OAuth Bearer Token
);

$result = $transactions->list();

if ($result['success']) {
    foreach ($result['transactions'] as $transaction) {
        // trid, date, amount, payment_method, status
    }
}

Eventos

O pacote emite eventos ao longo do ciclo de vida de cada pagamento. Registe listeners para reagir a criacoes, pagamentos, expiracoes e callbacks.

Eventos de criacao

Sucesso	Falha
MBReferenceCreated	MBReferenceCreationFailed
MBWayReferenceCreated	MBWayReferenceCreationFailed
CreditCardReferenceCreated	CreditCardReferenceCreationFailed
CreditCardRecurrenceAuthorizationCreated	CreditCardRecurrenceAuthorizationCreationFailed
CreditCardRecurringPaymentCreated	CreditCardRecurringPaymentCreationFailed
GooglePayReferenceCreated	GooglePayReferenceCreationFailed
ApplePayReferenceCreated	ApplePayReferenceCreationFailed

Eventos de pagamento e expiracao

Pagamento	Expiracao
MBReferencePaid	MBReferenceExpired
MBWayReferencePaid	MBWayReferenceExpired
CreditCardReferencePaid	--
GooglePayReferencePaid	--
ApplePayReferencePaid	--

Adicionalmente, os eventos CallbackReceived e InvalidCallbackReceived sao emitidos para todos os callbacks.

Registar listeners

Todos os eventos estao no namespace DigitaldevLx\LaravelEupago\Events.

Auto-discovery (recomendado): Crie uma classe listener em app/Listeners/ — o Laravel descobre-a automaticamente pelo type-hint do metodo handle():

app/Listeners/HandleMBPayment.php (Auto-discovery)

php

namespace App\Listeners;

use DigitaldevLx\LaravelEupago\Events\MBReferencePaid;
use Illuminate\Support\Facades\Mail;

class HandleMBPayment
{
    public function handle(MBReferencePaid $event): void
    {
        $reference = $event->reference;

        // Atualizar estado da encomenda
        $reference->mbable->update(['status' => 'paid']);

        // Enviar email de confirmacao
        Mail::to($reference->mbable->user)->send(
            new \App\Mail\PaymentConfirmed($reference)
        );
    }
}

Registo manual: Registe listeners no AppServiceProvider:

AppServiceProvider.php

php

use DigitaldevLx\LaravelEupago\Events\MBReferencePaid;
use Illuminate\Support\Facades\Event;

public function boot(): void
{
    Event::listen(
        MBReferencePaid::class,
        SendPaymentConfirmationEmail::class,
    );
}

Closure listeners:

Closure listener

php

use DigitaldevLx\LaravelEupago\Events\MBReferencePaid;
use Illuminate\Support\Facades\Event;

Event::listen(function (MBReferencePaid $event) {
    $reference = $event->reference;

    // Atualizar estado da encomenda
    $reference->mbable->update(['status' => 'paid']);
});

Verificar referencias expiradas

O comando eupago:check-expired identifica referencias Multibanco expiradas e emite o evento MBReferenceExpired para cada uma.

Comando e agendamento

bash

php artisan eupago:check-expired

routes/console.php (Laravel 11/12/13)

php

use Illuminate\Support\Facades\Schedule;

Schedule::command('eupago:check-expired')->daily();

Testes

O pacote fornece factories para todos os modelos de referencia de pagamento, com estados pre-definidos para simular pagamentos e expiracoes.

Factories com estados

php

use DigitaldevLx\LaravelEupago\Models\MbReference;
use DigitaldevLx\LaravelEupago\Models\MbwayReference;
use DigitaldevLx\LaravelEupago\Models\CreditCardReference;
use DigitaldevLx\LaravelEupago\Models\GooglePayReference;
use DigitaldevLx\LaravelEupago\Models\ApplePayReference;

// Referencia por pagar (default)
$reference = MbReference::factory()->create();

// Referencia paga
$paidReference = MbReference::factory()->paid()->create();

// Referencia expirada
$expiredReference = MbReference::factory()->expired()->create();

// Outros metodos de pagamento
$mbwayRef = MbwayReference::factory()->create();
$ccRef = CreditCardReference::factory()->paid()->create();
$gpayRef = GooglePayReference::factory()->create();
$appleRef = ApplePayReference::factory()->paid()->create();

Executar testes e ferramentas de qualidade

bash

# Testes completos
composer test

# Com cobertura (minimo 50%)
composer test:coverage

# Teste especifico
vendor/bin/pest tests/Unit/MB/MBTest.php

# Analise estatica
composer analyse

# Formatacao de codigo
composer lint

Boas Praticas

Usar ambiente test para desenvolvimento

Configure sempre EUPAGO_ENV=test em ambientes de desenvolvimento e staging. Teste todos os fluxos de pagamento antes de mudar para prod.

Usar traits Eloquent

Adicione as traits Mbable, Mbwayable, Creditcardable, etc. aos models para aceder facilmente as referencias de pagamento e manter uma relacao limpa entre encomendas e transacoes.

Tratar todos os eventos

Nao trate apenas o evento de sucesso. Registe listeners para eventos de falha e expiracao para manter o estado das encomendas consistente e notificar os clientes adequadamente.

Agendar verificacao de expiracoes

Execute o comando eupago:check-expired diariamente via scheduler para detetar e tratar automaticamente referencias Multibanco expiradas.

Handlers idempotentes

Os callbacks podem ser recebidos mais de uma vez. Garanta que os seus listeners sao idempotentes -- verificar o estado atual antes de processar evita duplicacoes e inconsistencias.

Validar montantes nos callbacks

Quando receber um callback de pagamento, compare sempre o montante recebido com o montante esperado na sua base de dados. Nunca confie apenas no valor do callback.

$ composer require digitaldev-lx/laravel-eupago

Pronto para integrar pagamentos?

Consulte o repositorio no GitHub para a documentacao completa, issues e contribuicoes.

Ver no GitHub ← Todos os Packages