> LOADING LARAVEL-EUPAGO v3.0...

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 que integra a sua aplicacao Laravel com o gateway de pagamentos EuPago, um dos principais processadores de pagamentos em Portugal. O pacote oferece uma API expressiva e fluente para gerir multiplos metodos de pagamento, com um sistema completo de eventos para acompanhar o ciclo de vida de cada transacao.

PHP 8.3+ Laravel 11-12 MIT License Pest 80%+ Coverage Larastan Level 5

Metodos de pagamento suportados

Multibanco -- referencias com callback automatico
MB Way -- pagamento movel instantaneo
Cartoes de Credito -- pagamentos unicos e subscricoes recorrentes
Google Pay -- wallet digital Google
Apple Pay -- wallet digital Apple
Payouts -- transferencias e relatorios de 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 --tag=eupago-migrations
php artisan migrate

Opcionalmente, publique o ficheiro de configuracao e as traducoes:

Opcional

bash

php artisan vendor:publish --tag=eupago-config
php artisan vendor:publish --tag=eupago-translations

Configuracao

Adicione as seguintes variaveis ao ficheiro .env:

.env

bash

EUPAGO_ENV=sandbox
EUPAGO_API_KEY=your-api-key-here
EUPAGO_CHANNEL=your-channel-id

Variaveis de ambiente

Variavel	Descricao	Default
EUPAGO_ENV	Ambiente: `sandbox` ou `production`	sandbox
EUPAGO_API_KEY	Chave de autenticacao da API EuPago	--
EUPAGO_CHANNEL	Identificador do canal de pagamento	--

O ficheiro de configuracao publicado em config/eupago.php permite personalizar opcoes adicionais como timeouts, retry logic e URLs de callback.

Metodos de Pagamento

Todos os metodos de pagamento sao acedidos atraves da facade EuPago. Cada metodo retorna um objeto com a referencia criada e o estado da transacao.

Multibanco

Gere referencias Multibanco com callback automatico quando o pagamento e efetuado. O metodo mais utilizado em Portugal para pagamentos online.

Multibanco

php

use DigitaldevLx\LaravelEupago\Facades\EuPago;

$reference = EuPago::multibanco()
    ->create([
        'order_id' => 'ORDER-001',
        'amount' => 49.99,
    ]);

// $reference->entity     - Entidade Multibanco
// $reference->reference  - Referencia de pagamento
// $reference->amount     - Valor
// $reference->status     - Estado atual

MB Way

Pagamento movel instantaneo. O utilizador recebe uma notificacao na app MB Way e confirma com PIN.

MB Way

php

$mbway = EuPago::mbway()
    ->create([
        'order_id' => 'ORDER-002',
        'amount' => 29.99,
        'phone' => '912345678',
    ]);

Cartoes de Credito

Pagamentos unicos com cartao de credito. O utilizador e redirecionado para a pagina de pagamento seguro.

Cartao de Credito - Pagamento Unico

php

$card = EuPago::creditCard()
    ->create([
        'order_id' => 'ORDER-003',
        'amount' => 99.99,
        'success_url' => route('payment.success'),
        'error_url' => route('payment.error'),
        'cancel_url' => route('payment.cancel'),
    ]);

// Redirecionar o utilizador para a pagina de pagamento
return redirect($card->redirect_url);

Para subscricoes recorrentes com cartao de credito:

Cartao de Credito - Subscricao

php

$subscription = EuPago::creditCard()
    ->createSubscription([
        'order_id' => 'SUB-001',
        'amount' => 9.99,
        'frequency' => 'monthly',
        'max_retries' => 3,
    ]);

Google Pay

Aceite pagamentos via Google Pay com uma experiencia de checkout rapida.

Google Pay

php

$gpay = EuPago::googlePay()
    ->create([
        'order_id' => 'ORDER-004',
        'amount' => 59.99,
        'success_url' => route('payment.success'),
        'error_url' => route('payment.error'),
    ]);

Apple Pay

Aceite pagamentos via Apple Pay para utilizadores de dispositivos Apple.

Apple Pay

php

$apple = EuPago::applePay()
    ->create([
        'order_id' => 'ORDER-005',
        'amount' => 59.99,
        'success_url' => route('payment.success'),
        'error_url' => route('payment.error'),
    ]);

Payouts

Envie transferencias bancarias e consulte relatorios de transacoes.

Payouts - Criar Transferencia

php

$payout = EuPago::payout()
    ->create([
        'amount' => 100.00,
        'iban' => 'PT50000201231234567890154',
        'name' => 'John Doe',
    ]);

Payouts - Relatorio de Transacoes

php

$transactions = EuPago::payout()->getTransactions([
    'start_date' => '2024-01-01',
    'end_date' => '2024-12-31',
    'per_page' => 100,
    'page' => 1,
]);

Eventos

O pacote emite eventos ao longo do ciclo de vida de cada pagamento. Registe listeners para reagir a mudancas de estado -- por exemplo, atualizar o estado de uma encomenda quando o pagamento e confirmado.

Eventos disponiveis

Metodo	Evento
Multibanco	MultibancoPaidEvent
Multibanco	MultibancoFailedEvent
Multibanco	MultibancoExpiredEvent
MB Way	MbwayPaidEvent
MB Way	MbwayDeclinedEvent
MB Way	MbwayExpiredEvent
MB Way	MbwayErrorEvent
Credit Card	CreditCardPaidEvent
Credit Card	CreditCardFailedEvent

Registar listeners

Registe os listeners no metodo boot() do AppServiceProvider (Laravel 11/12):

app/Providers/AppServiceProvider.php

php

use Illuminate\Support\Facades\Event;
use DigitaldevLx\LaravelEupago\Events\MultibancoPaidEvent;
use DigitaldevLx\LaravelEupago\Events\MbwayPaidEvent;

public function boot(): void
{
    Event::listen(MultibancoPaidEvent::class, function ($event) {
        $reference = $event->reference;

        Order::where('payment_reference', $reference->reference)
            ->update(['status' => 'paid']);
    });

    Event::listen(MbwayPaidEvent::class, function ($event) {
        $reference = $event->reference;

        Order::where('payment_reference', $reference->reference)
            ->update(['status' => 'paid']);

        // Enviar notificacao ao cliente
        $reference->order->user->notify(
            new PaymentConfirmedNotification($reference)
        );
    });
}

Boas Praticas

Usar ambiente sandbox para desenvolvimento

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

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.

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.

Registar atividade de pagamento

Faca log de todas as transacoes e callbacks para auditoria. Em caso de disputa, ter um registo completo e essencial.

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.

Usar queues para processar callbacks

Processe os callbacks de pagamento em background jobs para garantir que a resposta ao EuPago e rapida e que o processamento e fiavel com retries automaticos.

Testes

O pacote fornece factories para todos os modelos de referencia de pagamento, facilitando a criacao de dados de teste realistas nos seus testes.

Usar factories nos testes

php

use DigitaldevLx\LaravelEupago\Models\MultibancoReference;

// Criar referencia Multibanco de teste
$reference = MultibancoReference::factory()->create([
    'amount' => 49.99,
    'status' => 'pending',
]);

// Simular pagamento
$reference->update(['status' => 'paid']);

// Verificar que a encomenda foi atualizada
$this->assertDatabaseHas('orders', [
    'payment_reference' => $reference->reference,
    'status' => 'paid',
]);

Executar os testes do pacote

Executar testes

bash

# Testes completos
vendor/bin/pest

# Com cobertura
vendor/bin/pest --coverage --min=80

# Analise estatica
vendor/bin/phpstan analyse

O pacote mantem uma cobertura minima de 80% e utiliza Larastan Level 5 para analise estatica. Recomendamos manter o mesmo nivel de qualidade nos seus testes de integracao.

$ 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