Download the PHP package techsolutions-projects/mobile-wallet-sdk without Composer

Mobile Wallet SDK — Documentação Oficial

Pacote: techsolutions-projects/mobile-wallet-sdk Namespace: Techsolutions\Sdk\MobileWallets Compatibilidade: PHP 8.2–8.3 · Laravel 11–13 Licença: MIT — Techsolutions Lda

Índice

1. Introdução
2. Instalação e Configuração
3. Arquitectura
4. Conceitos Principais
5. Utilização Básica
6. API Fluente (Transaction Builder)
7. Trait Billable
8. Facade
9. Enumerações
10. Códigos de Resposta
11. Sistema de Retry
12. Eventos
13. Webhooks
14. WebSockets / Broadcasting
15. Dashboard
16. Drivers
17. Gateways Externos
18. Internacionalização
19. Testes
20. Análise Estática e Qualidade de Código
21. Extensão — Criar um Driver Customizado
22. Referência de Configuração
23. FAQ

1. Introdução

O Mobile Wallet Gateway é um pacote Laravel que permite integrar múltiplas carteiras móveis moçambicanas através de uma única interface consistente.

O objectivo é simplificar a integração com APIs de pagamento como M-Pesa e E-Mola, garantindo ao mesmo tempo robustez, extensibilidade e qualidade de código.

Porquê este pacote?

Integrar directamente com cada provedor de pagamento móvel em Moçambique apresenta desafios:

• O M-Pesa (Vodacom) utiliza uma API REST com autenticação RSA.
• O E-Mola (Movitel) utiliza um WebService SOAP/WSDL — um protocolo completamente diferente.
• Cada provedor tem os seus próprios códigos de resposta, formatos de payload e fluxos de callback.
• Não existe padronização entre eles.

Este pacote resolve estes problemas ao fornecer:

• Uma interface única para todos os provedores.
• Um sistema de drivers que abstrai as diferenças de protocolo.
• Tipagem forte (declare(strict_types=1)) em todos os ficheiros.
• Enumerações para estados, tipos de transacção e códigos de resposta.
• Retry inteligente que distingue erros transitórios de erros terminais.
• Internacionalização completa (PT pré-reforma e EN).

Princípios de design

• Fortemente tipado — Todos os ficheiros utilizam declare(strict_types=1). Parâmetros, retornos e propriedades são tipados.
• Laravel-native — Service Container, Service Provider, Facades, Jobs, Events, Broadcasting, Queues, Eloquent.
• SOLID — Cada classe tem uma única responsabilidade. Os drivers são substituíveis. O sistema é extensível sem modificação.
• Execução lazy — Nenhuma operação é executada até se invocar begin(), c2b(), b2c(), etc.

2. Instalação e Configuração

Requisitos

• PHP 8.1 ou superior
• Laravel 10, 11, 12 ou 13
• Extensão PHP ext-openssl (para M-Pesa)
• Extensão PHP ext-soap (para E-Mola)

Instalar via Composer

Publicar ficheiros

Publicar tudo de uma vez:

Ou separadamente:

Executar as migrations

Isto cria duas tabelas:

Registar as carteiras

Antes de processar transacções, é necessário inserir as carteiras na base de dados:

Nota: Recomenda-se criar um seeder (MwgWalletSeeder) para automatizar este processo.

Configuração do ambiente (.env)

3. Arquitectura

O pacote segue uma arquitectura baseada em drivers, inspirada no padrão Manager do Laravel (à semelhança do DatabaseManager, MailManager, FilesystemManager).

Diagrama de camadas

Estrutura do pacote

Fluxo de uma transacção

1. O programador invoca Transaction::onWallet($wallet)->c2b(...).
2. O TransactionBuilder acumula configurações (callbacks, canal WebSocket, metadata).
3. Ao invocar c2b() / b2c() / begin(), o builder cria um registo Transaction na base de dados com estado PENDING.
4. O builder despacha um ProcessTransactionJob (síncrono ou via fila).
5. O job resolve o driver correcto via GatewayManager.
6. O driver chama a API do provedor (HTTP para M-Pesa, SOAP para E-Mola).
7. Com base na resposta:
   • Sucesso → marca como SUCCEEDED, dispara TransactionSucceeded, executa callback.
   • Falha retentável → agenda retry com backoff exponencial, dispara TransactionRetried.
   • Falha terminal → marca como FAILED, dispara TransactionFailed, executa callback.

4. Conceitos Principais

Wallet

Representa um provedor de pagamento registado na base de dados. Cada carteira tem um name que corresponde a um driver.

Campos:

Transaction

Representa uma transacção de pagamento com o seu estado completo.

Campos principais:

GatewayResponse

DTO (Data Transfer Object) imutável que encapsula a resposta de um gateway.

5. Utilização Básica

Transacção C2B (Cliente para Empresa)

O caso mais comum — cobrar um pagamento ao cliente:

Transacção B2C (Empresa para Cliente)

Desembolsar fundos para um cliente:

Formatos de valor aceites

O AmountParser aceita múltiplos formatos:

6. API Fluente (Transaction Builder)

O TransactionBuilder é o coração da API fluente. Todos os métodos de configuração são opcionais e encadeáveis. A transacção só é criada quando se invoca um método terminal (begin(), c2b(), b2c(), etc.).

Exemplo completo

Métodos de configuração

Métodos terminais (executam a transacção)

7. Trait Billable

O trait MwgBillable permite que qualquer modelo Eloquent se torne "pagável" — criando uma ligação directa entre o que está a ser pago e a transacção.

Implementar no modelo

O modelo deve implementar a interface Billable e usar o trait MwgBillable:

Interface Billable

Métodos disponibilizados pelo trait

Pagamento directo

Builder fluente com billable

Consultas

Como funciona a ligação polimórfica

Quando se utiliza o trait, as colunas billable_type e billable_id na tabela mws_transactions são preenchidas automaticamente:

Isto permite:

8. Facade

A facade MobileWallet fornece um ponto de acesso estático ao GatewayManager:

A facade está registada como alias MWS no composer.json:

9. Enumerações

Todos os valores discretos do pacote são representados por enumerações PHP 8.1, garantindo segurança de tipo em tempo de compilação.

TransactionStatus

Estados possíveis de uma transacção:

TransactionType

Tipos de transacção suportados:

WalletDriver

Drivers disponíveis com resolução de aliases:

GatewayResponseCode

Detalhado na secção seguinte.

10. Códigos de Resposta

O enum GatewayResponseCode unifica os códigos de resposta de todos os provedores num único enum. Cada caso é prefixado com M_PESA_* ou E_MOLA_*.

Códigos M-Pesa

Códigos E-Mola

Conforme a MOVITEL USSD PUSH API SPECIFICATION v1.5, a E-Mola devolve dois níveis de código de resposta: o nível transacção (<errorCode>, prefixo EMOLA-) e o nível gateway BCCS (<error>, prefixo EMOLA-GW-). Abaixo um subconjunto dos mais relevantes — a tabela completa está em src/Enums/GatewayResponseCode.php.

Nível transacção:

Nível gateway (BCCS):

Transporte (gerados pelo driver):

Utilização

11. Sistema de Retry

O pacote inclui retry automático com backoff exponencial e decisão inteligente baseada nos códigos de resposta.

Configuração

Comportamento padrão

1. Se a resposta é um sucesso → para. Marca como SUCCEEDED.
2. Se a resposta é uma falha terminal (ex.: INS-5 saldo insuficiente) → para imediatamente. Marca como FAILED. Não há razão para re-tentar.
3. Se a resposta é uma falha retentável (ex.: INS-22 timeout) e current_attempt < max_attempts → agenda nova tentativa com backoff exponencial.
4. Se as tentativas se esgotam → marca como FAILED.

Override via shouldRetry()

12. Eventos

O pacote dispara eventos Laravel em cada ponto do ciclo de vida da transacção:

Registar listeners

Exemplo de listener

13. Webhooks

Os provedores de pagamento enviam notificações assíncronas (callbacks) quando o estado de uma transacção muda. O pacote fornece um endpoint pronto a usar.

Endpoints

O prefixo pode ser alterado em config/mobile-wallet.php:

Segurança

Quando MWS_WEBHOOK_SECRET está definido, o middleware VerifyWebhookSignature valida:

1. A presença dos cabeçalhos X-MWS-Signature e X-MWS-Timestamp.
2. A tolerância temporal (por defeito 5 minutos).
3. A assinatura HMAC-SHA256 do payload.

Configurar no provedor

Ao configurar webhooks no portal M-Pesa ou no acordo E-Mola, forneça:

14. WebSockets / Broadcasting

O pacote suporta notificações em tempo real via Laravel Broadcasting (Echo + Pusher/Soketi/Ably).

Activar

Utilizar

Ouvir no frontend (Laravel Echo)

Payload do broadcast

15. Dashboard

O pacote inclui endpoints JSON para um painel de controlo simples.

Activar

Endpoints

O middleware por defeito é ['web', 'auth'] — configurável em config/mobile-wallet.php.

16. Drivers

M-Pesa (Vodacom Moçambique)

Endpoints utilizados:

E-Mola (Movitel Moçambique)

Operações SOAP — uma única operação gwOperation cujo wscode determina a acção:

A resposta tem dois níveis: a tag <error> no <Result> reflecte o estado do gateway BCCS (→ EMOLA-GW-*) e o <errorCode> real da transacção fica dentro do CDATA <original> (→ EMOLA-*). O driver faz o parsing dos dois automaticamente.

Métodos adicionais expostos por EMolaGateway:

Nota importante: A E-Mola não disponibiliza uma API pública para developers. As credenciais (WSDL URL, username, password, key, partner code) são obtidas exclusivamente através de acordo comercial directo com a Movitel. A extensão PHP ext-soap é necessária para usar este driver directamente.

Sandbox

Driver de simulação para desenvolvimento e testes. Não faz chamadas HTTP/SOAP reais.

17. Gateways Externos

O pacote suporta integração com plataformas intermediárias que já implementaram a comunicação directa com os provedores. Em vez de cada developer obter credenciais directas da Vodacom ou fazer acordo de parceria com a Movitel, pode utilizar um intermediário que abstrai tudo numa API REST simples.

Conceito

O código da tua aplicação não muda — a mesma API fluente funciona independentemente de estar a usar a API directa ou um intermediário. A diferença está apenas na configuração.

Presets disponíveis

Activar para uma wallet

Para usar a EACACIA em vez da API directa do M-Pesa, basta alterar a configuração:

O código da aplicação continua exactamente igual:

Configuração por preset

EACACIA (Vitae ERP)

O preset eacacia já sabe:

• Que o endpoint C2B para M-Pesa é /api/eacacia/mpesa/c2b
• Que o endpoint C2B para E-Mola é /api/eacacia/emola/c2b
• Que o campo msisdn deve ser enviado como phone_number
• Que o sucesso é response_code === 'success'
• Que o ID da transacção está em details.reference

e2Payments (Explicador)

Gateway Customizado

Para qualquer API REST que não tenha um preset:

Códigos de resposta de gateways externos

Misto: wallet directa + wallet externa

Pode-se ter uma wallet com driver directo e outra com externo no mesmo projecto:

18. Internacionalização

O pacote inclui ficheiros de tradução em Português Europeu (pré-reforma) e Inglês.

Ficheiros de língua

Utilização automática

Os enums utilizam o sistema de tradução automaticamente:

Publicar para customização

Os ficheiros são copiados para lang/vendor/mobile-wallet/.

19. Testes

O pacote inclui testes unitários e de integração utilizando o Orchestra Testbench.

Executar

Cobertura

Testar nos teus projectos

O SandboxGateway é activado automaticamente quando MWS_SANDBOX=true. Nos teus testes:

20. Análise Estática e Qualidade de Código

O pacote inclui configuração para Larastan (PHPStan para Laravel) e Rector.

Larastan (PHPStan nível 8)

Configuração em phpstan.neon — nível 8 (o mais rigoroso).

Rector

Configuração em rector.php — inclui sets de qualidade de código, tipos, early return e dead code.

21. Extensão — Criar um Driver Customizado

Para adicionar suporte a um novo provedor (ex.: mKesh, se a API for disponibilizada no futuro):

1. Criar o driver

2. Registar no GatewayManager

3. Adicionar configuração

4. Registar a wallet na base de dados

22. Referência de Configuração

Todas as opções disponíveis em config/mobile-wallet.php:

23. FAQ

P: Posso usar sem filas (synchronous)?

Sim. Defina MWS_QUEUE_ENABLED=false no .env. O ProcessTransactionJob será executado sincronicamente via dispatch_sync().

P: Os callbacks onSuccess/onFail funcionam com filas?

Sim. Os closures são serializados usando Illuminate\Queue\SerializableClosure. No entanto, tome cuidado para não capturar objectos complexos ou não serializáveis na closure.

P: A E-Mola suporta B2B e C2C?

Não. A API SOAP da E-Mola suporta oficialmente apenas C2B. O suporte a B2C (desembolso) depende do acordo de parceria com a Movitel. B2B e C2C não são suportados — tentar utilizá-los lançará um GatewayException.

P: Como mudo para produção?

1. Defina MWS_SANDBOX=false no .env.
2. Altere MWS_MPESA_BASE_URL para a URL de produção: https://api.vm.co.mz.
3. Use credenciais de produção para M-Pesa e E-Mola.
4. Configure MWS_WEBHOOK_SECRET com uma chave forte.

P: O pacote cria alguma rota automaticamente?

Sim:

• POST /mws/webhook/{wallet} — sempre registada (protegida por middleware).
• GET /mws/dashboard e GET /mws/dashboard/transaction/{uuid} — apenas quando MWS_DASHBOARD_ENABLED=true.

P: Posso adicionar novos provedores no futuro?

Sim. Consulte a secção 20. Extensão. O sistema de drivers permite adicionar novos provedores sem alterar o código do pacote.

P: Como funciona o retry inteligente?

O ProcessTransactionJob consulta o GatewayResponseCode enum para determinar se o erro é retentável ou terminal. Erros como "saldo insuficiente" (INS-5) ou "cancelado pelo cliente" (INS-6) são terminais — o pacote para imediatamente em vez de desperdiçar tentativas. Erros como "timeout" (INS-22) ou "erro do servidor" (INS-999) são retentáveis.

P: Como sei qual versão do PHP/Laravel é suportada?

Documentação mantida por Techsolutions Lda.