noopstudios / laravel-eupago
Multibanco references and MB WAY payments through the EuPago API for Laravel, with an optional Filament plugin.
Requires
- php: ^8.3
- illuminate/console: ^13.0
- illuminate/contracts: ^13.0
- illuminate/database: ^13.0
- illuminate/http: ^13.0
- illuminate/queue: ^13.0
- illuminate/routing: ^13.0
- illuminate/support: ^13.0
Requires (Dev)
- filament/filament: ^5.0
- larastan/larastan: ^3.0
- laravel/pint: ^1.0
- orchestra/testbench: ^11.0
- pestphp/pest: ^4.0 || ^5.0
- pestphp/pest-plugin-laravel: ^4.0 || ^5.0
Suggests
- filament/filament: Required for the EuPago panel plugin (^5.0): payment attempts and webhook events.
Provides
None
Conflicts
None
Replaces
None
README
Referências Multibanco e pedidos MB WAY através da API REST do EuPago, com confirmação por Webhooks 2.0. O pacote não conhece encomendas nem faturação: recebe um modelo Eloquent (o "payable"), um valor em cêntimos e devolve uma tentativa de pagamento; quando o EuPago confirma, chama a tua aplicação.
Requisitos: PHP ^8.3, Laravel 13. Filament v5 é opcional (só para o painel).
Instalação
composer require noopstudios/laravel-eupago php artisan migrate # as migrações são carregadas pelo pacote php artisan vendor:publish --tag=eupago-config # opcional
Configuração
EUPAGO_API_KEY= EUPAGO_WEBHOOK_SECRET= # a "chave criptográfica" dos Webhooks 2.0 do canal EUPAGO_SANDBOX=false # true usa sandbox.eupago.pt em vez de clientes.eupago.pt EUPAGO_PREFIX= # prefixo do identificador ("PREFIXO-ULID"); permite várias apps no mesmo canal
Opções só em config/eupago.php:
| Chave | Por omissão | Significado |
|---|---|---|
multibanco_days |
3 |
Dias de validade da referência (até ao fim desse dia, Europe/Lisbon) |
mbway_minutes |
5 |
Minutos que o cliente tem para aprovar o pedido MB WAY |
max_attempts |
5 |
Tentativas por payable |
webhook_path |
eupago/webhook |
Caminho do webhook |
permissions |
ver Filament | Abilities do painel |
O que a aplicação tem de ter
- Um queue worker: os eventos do webhook são processados por um job.
- Um
HandlesEupagoPaymentsregistado no container (ver Receber pagamentos): sem ele os eventos do webhook ficampendinge oeupago:expirereporta um erro em cada execução. - O scheduler a correr: o pacote agenda
eupago:expire(cada minuto) eeupago:recover(cada cinco minutos). Sem eles as tentativas não expiram e os eventos perdidos não são recuperados. Oeupago:expiresó fecha uma tentativa 2 minutos depois deexpires_ate espera enquanto houver um evento do webhookpendingpara ela, para não expirar um pagamento feito a tempo. - Uma cache com locks partilhada por todos os servidores e processos (Redis, base de dados…): o lock por payable evita referências duplicadas.
arrayefilenão servem com mais de um processo. - Nada de
Eupago::multibanco()/mbway()dentro de uma transação de base de dados: o pacote lança uma exceção, porque um rollback apagaria o registo que impede uma segunda referência para o mesmo payable. - A mesma
APP_KEY: os corpos dos webhooks são guardados encriptados com ela; se a rodares, os eventos antigos deixam de ser legíveis. - Trusted proxies configurados, se estiveres atrás de um proxy ou load balancer: a rota do webhook tem throttle por IP (120 pedidos por minuto).
Pedir pagamentos
use Noop\Eupago\Facades\Eupago; $attempt = Eupago::multibanco($order, 1250); // 12,50 € $attempt = Eupago::mbway($order, 1250, '912345678'); // o pedido segue para a app MB WAY do cliente
Ambos devolvem um PaymentAttempt com entity, reference, amount_cents, identifier, expires_at e status, e payable para voltar ao modelo. Só devolvem quando a tentativa está pending.
Regras:
- Uma tentativa Multibanco
pendingdo mesmo valor e ainda válida é reutilizada; um valor diferente cria uma nova referência. - MB WAY envia sempre um pedido novo.
- Se a resposta se perder, a tentativa fica
unknown: pode existir uma referência no EuPago, por isso nunca é repetida automaticamente e bloqueia novos pedidos desse payable até o webhook a completar, expirar, ou um operador a marcar como falhada. - Um payable não passa de
max_attemptstentativas. Contam todas as que chegaram ao cliente (pending,paid,expired, efailedcom referência), mais as recusas dos últimos 15 minutos; recusas explícitas sem referência (chave errada, telemóvel inválido) deixam de contar ao fim desse tempo. Por exemplo, cinco pedidos MB WAY expirados bloqueiam o payable até um operador intervir. Para subir o limite, publica a configuração e alteramax_attemptsemconfig/eupago.php.
Os erros são EupagoException, com ->type (FailureType) e, quando existe, ->attempt:
use Noop\Eupago\Enums\FailureType; use Noop\Eupago\Exceptions\EupagoException; try { $attempt = Eupago::mbway($order, 1250, $phone); } catch (EupagoException $e) { match ($e->type) { FailureType::Rejected => /* recusado (ou valor/telemóvel inválido): podes tentar outra vez */, FailureType::Unknown => /* resultado incerto: não repitas, pode já existir referência */, FailureType::Blocked => /* pedido em curso, tentativa por resolver ou limite atingido */, }; }
Receber pagamentos
Implementa HandlesEupagoPayments e regista-o no container:
use Noop\Eupago\Contracts\HandlesEupagoPayments; use Noop\Eupago\Data\ConfirmedPayment; use Noop\Eupago\Models\PaymentAttempt; class OrderPayments implements HandlesEupagoPayments { public function canReceive(PaymentAttempt $attempt): bool { return $attempt->payable->isAwaitingPayment(); } public function received(PaymentAttempt $attempt, ConfirmedPayment $payment): void { $attempt->payable->markPaid($payment->amountCents, $payment->paidAt); } public function expired(PaymentAttempt $attempt): void { // a tentativa terminou sem pagamento (expirou, foi cancelada ou falhou) } } // AppServiceProvider::register() $this->app->bind(HandlesEupagoPayments::class, OrderPayments::class);
canReceive()devolvefalsequando a aplicação já não aceita o pagamento (encomenda cancelada, por exemplo). A tentativa fica na mesmapaide é despachadoPaymentNeedsReview: o dinheiro entrou e alguém tem de o tratar.expired()é chamado por tentativa, não por payable: outras tentativas do mesmo payable podem estar aindapendingou jápaid, por isso não canceles a encomenda às cegas. E umexpired()ainda pode ser seguido de um PAID tardio dessa tentativa, que passa então porcanReceive().received()eexpired()correm dentro da transação do pacote: se lançarem uma exceção, tudo é revertido e o evento é repetido.- Eventos (todos com
->attempt, despachados depois do commit):PaymentConfirmed,PaymentNeedsReview,PaymentAttemptExpired.
Webhook
No backoffice do EuPago, no canal, em Webhooks 2.0:
- Endpoint:
https://a-tua-app.pt/eupago/webhook(tem de ser acessível publicamente por HTTPS). - Encriptar Webhook: Não. Com "Sim", o EuPago assina a string encriptada
datae a entrega falha a verificação da assinatura (401). - Tipos de evento: Pagamento, Cancelamento, Expiração, Erro.
- Copia a chave criptográfica do canal para
EUPAGO_WEBHOOK_SECRET.
Verificação: o cabeçalho X-Signature é o HMAC-SHA256 do corpo bruto, com essa chave, em base64. Respostas: 200 (guardado, ou duplicado), 401 assinatura inválida, 422 corpo assinado sem identifier ou status, 503 segredo não configurado. O mesmo corpo é guardado uma só vez, por isso reenvios são inofensivos; o EuPago volta a tentar durante 24 h.
Nota: o formato da assinatura foi confirmado com uma entrega real na sandbox do EuPago. Uma entrega recusada por assinatura inválida ou em falta fica registada nos logs como warning (sem o corpo nem a assinatura).
Estados de um evento, úteis para quem opera:
| Estado | Significado |
|---|---|
pending |
À espera de processamento (ou a falhar e a ser repetido) |
processed |
Aplicado à tentativa |
rejected |
Pagamento com valor, referência ou entidade diferentes da tentativa, ou sem referência de nenhum dos lados; é comunicado ao exception handler da aplicação |
orphaned |
Nenhuma tentativa com esse identificador |
Filament (opcional)
->plugins([\Noop\Eupago\Filament\EupagoPlugin::make()])
Mostra as tentativas e os eventos (traduções só para o locale pt). O acesso segue as quatro abilities de config('eupago.permissions'), que concedes via Gate ou um pacote de permissões:
| Chave | Ability por omissão |
|---|---|
view_attempts |
view eupago attempts |
view_events |
view eupago events |
reprocess_events |
reprocess eupago events |
abandon_attempts |
abandon eupago attempts |
Uma permissão null não concede nada. Duas ações:
- Reprocessar um evento
pending,rejectedouorphaned: volta apendinge é processado de novo. Um eventoprocessednunca é reprocessado. - Dar como falhada uma tentativa
unknown: só depois de confirmares no backoffice do EuPago que não existe referência nem pedido para esse identificador. Liberta o payable e fecha a tentativa como as outras (expired()ePaymentAttemptExpired). Se afinal existir e for paga mais tarde, o webhook continua a marcá-la como paga.
Testes
Nos testes da tua aplicação, Eupago::fake() impede qualquer pedido à rede mas mantém todas as regras; pay() e expire() simulam o webhook através do processamento real, por isso o teu handler e os eventos disparam como em produção:
$fake = Eupago::fake(); $attempt = Eupago::multibanco($order, 1250); $fake->pay($attempt); // ou $fake->expire($attempt) expect($order->fresh()->isPaid())->toBeTrue();
A suite do pacote: vendor/bin/pest. A suite contra a sandbox real (cria uma referência Multibanco e um pedido MB WAY reais na sandbox; ver .env.sandbox.example):
EUPAGO_SANDBOX_ENV=/caminho/para/ficheiro vendor/bin/pest --group=sandbox
Fora do âmbito da v0.1
Cartão, débito direto, reembolsos, consulta do estado à API (polling) e webhooks encriptados.
Licença
MIT.