PHPackages brilliant\_mind/m-pesa - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Payment Processing](/categories/payments) 4. / 5. brilliant\_mind/m-pesa ActiveLibrary[Payment Processing](/categories/payments) brilliant\_mind/m-pesa ====================== MPesa package for laravel v1.1.0(4mo ago)0645↑246.2%MITPHPPHP ^8.1 Since Feb 28Pushed 1mo agoCompare [ Source](https://github.com/osvaldogeraldo/m-pesa)[ Packagist](https://packagist.org/packages/brilliant_mind/m-pesa)[ RSS](/packages/brilliant-mind-m-pesa/feed)WikiDiscussions main Synced today READMEChangelogDependencies (4)Versions (4)Used By (0) M-Pesa PHP SDK (Laravel) ======================== [](#m-pesa-php-sdk-laravel) SDK para interagir com a API M-Pesa Moçambique: C2B, B2B, B2C, consulta de transação e reversão. Índice ------ [](#índice) - [Instalação](#instala%C3%A7%C3%A3o) - [Configuração](#configura%C3%A7%C3%A3o) - [Variáveis de ambiente](#vari%C3%A1veis-de-ambiente) - [Tabela completa de variáveis](#tabela-completa-de-vari%C3%A1veis) - [Publicar o ficheiro de configuração](#publicar-o-ficheiro-de-configura%C3%A7%C3%A3o-opcional) - [Utilização](#utiliza%C3%A7%C3%A3o) - [C2B, B2B, B2C](#c2b--cliente-para-empresa) - [Consulta de transação](#consulta-de-transa%C3%A7%C3%A3o) - [Reversão](#revers%C3%A3o) - [O objecto Transaction](#o-objecto-transaction) - [Códigos de resposta](#c%C3%B3digos-de-resposta) - [Modo fake (testes)](#modo-fake-testes) - [Requisitos](#requisitos) - [Notas sobre portos M-Pesa](#notas-sobre-portos-m-pesa) Instalação ---------- [](#instalação) ``` composer require brilliant_mind/m-pesa ``` O pacote usa *package auto-discovery* do Laravel — o `ServiceProvider` e o alias `Mpesa` são registados automaticamente. Configuração ------------ [](#configuração) ### Variáveis de ambiente [](#variáveis-de-ambiente) #### Desenvolvimento (sandbox) [](#desenvolvimento-sandbox) ``` # MPESA DEVELOPMENT MPESA_API_KEY=sua_api_key_sandbox MPESA_PUBLIC_KEY=sua_public_key_sandbox MPESA_ENVIRONMENT=development MPESA_SERVICE_PROVIDER_CODE=171717 MPESA_ORIGIN=developer.mpesa.vm.co.mz MPESA_INITIATOR_IDENTIFIER= MPESA_SECURITY_CREDENTIAL= ``` #### Produção [](#produção) ``` # MPESA PRODUCTION MPESA_API_KEY=sua_api_key_producao MPESA_PUBLIC_KEY=sua_public_key_producao MPESA_ENVIRONMENT=production MPESA_SERVICE_PROVIDER_CODE=903153 MPESA_ORIGIN=developer.mpesa.vm.co.mz MPESA_INITIATOR_IDENTIFIER=seu_initiator MPESA_SECURITY_CREDENTIAL=seu_credential_encriptado ``` > **Nota:** `MPESA_ENV` continua a ser aceite como alias retrocompatível de `MPESA_ENVIRONMENT`. ### Tabela completa de variáveis [](#tabela-completa-de-variáveis) VariávelObrigatóriaDefaultDescrição`MPESA_API_KEY`**Sim**`''`Chave de API fornecida pelo portal da M-Pesa (sandbox ou produção).`MPESA_PUBLIC_KEY`**Sim**`''`Chave pública RSA (base64, sem cabeçalhos `-----BEGIN...`). Usada para encriptar o `MPESA_API_KEY` em cada chamada.`MPESA_ENVIRONMENT`Não`development``development` ou `production`. Determina o host por defeito (sandbox vs prod).`MPESA_SERVICE_PROVIDER_CODE`Não`171717`Código do *service provider*. `171717` é o valor de sandbox; em produção usa o teu código (ex. `903153`).`MPESA_HOST`NãoderivadoOverride manual do host. Por defeito a SDK escolhe `api.sandbox.vm.co.mz` (development) ou `api.vm.co.mz` (production). Só preenche se quiseres forçar outro endpoint.`MPESA_ORIGIN`Não`developer.mpesa.vm.co.mz`Valor do header `Origin` enviado a cada pedido.`MPESA_INITIATOR_IDENTIFIER`Apenas reversão`''`Identificador do *initiator* — obrigatório para `reversal()`.`MPESA_SECURITY_CREDENTIAL`Apenas reversão`''`Credencial encriptada do *initiator* — obrigatória para `reversal()`.> **`MPESA_PORT` não existe nesta SDK.** Os portos M-Pesa são por operação (`18352` C2B, `18345` B2C, `18349` B2B, `18353` query, `18354` reversal) e são geridos internamente. Podes ter `MPESA_PORT` no teu `.env` — será simplesmente ignorado. ### Publicar o ficheiro de configuração (opcional) [](#publicar-o-ficheiro-de-configuração-opcional) Só é necessário se quiseres alterar defaults além do `.env`: ``` php artisan vendor:publish --tag=mpesa-config ``` Isto cria `config/mpesa.php`. ### Configuração em runtime (multi-tenant) [](#configuração-em-runtime-multi-tenant) Quando as credenciais não vêm do `.env` (ex. são dinâmicas por tenant), podes chamar `Mpesa::config(...)` antes de cada operação: ``` use Mpesa; Mpesa::config( $apiKey, $publicKey, // $environment = null, // 'development' | 'production' // $serviceProviderCode = null, // ex. '903153' // $origin = null, // 'developer.mpesa.vm.co.mz' // $initiatorIdentifier = null, // só para reversal() // $securityCredential = null, // só para reversal() // $host = null, // override do host (raro) ); $tx = Mpesa::c2b($amount, $msisdn, $ref, $thirdPartyRef); ``` Quaisquer argumentos passados aqui sobrepõem-se aos do `.env` para o ciclo de vida do request actual. Args a `null` mantêm o valor previamente configurado. > **Não existe parâmetro `port`.** Os portos M-Pesa são por operação (ver [Notas sobre portos M-Pesa](#notas-sobre-portos-m-pesa)) e estão hardcoded na SDK. Se vires `config('services.mpesa.port')` em código antigo, pode ser removido. Utilização ---------- [](#utilização) Basta usar o facade `Mpesa` em qualquer lado (controllers, jobs, services): ``` use Mpesa; $transactionReference = bin2hex(random_bytes(6)); $thirdPartyReference = bin2hex(random_bytes(6)); $response = Mpesa::c2b(1, '258846000000', $transactionReference, $thirdPartyReference); return $response->toArray(); ``` ### C2B — Cliente para Empresa [](#c2b--cliente-para-empresa) ``` $response = Mpesa::c2b($amount, $msisdn, $transactionReference, $thirdPartyReference); ``` ParâmetroTipoDescrição`$amount``float`Valor a debitar do cliente.`$msisdn``string`MSISDN do cliente, formato internacional (ex. `258846000000`).`$transactionReference``string`Referência interna da transação (1–20 caracteres).`$thirdPartyReference``string`Referência única do lado do *third party* (idempotência).### B2C — Empresa para Cliente [](#b2c--empresa-para-cliente) ``` $response = Mpesa::b2c($amount, $msisdn, $transactionReference, $thirdPartyReference); ``` ### B2B — Empresa para Empresa [](#b2b--empresa-para-empresa) ``` $response = Mpesa::b2b($amount, $msisdn, $transactionReference, $thirdPartyReference); ``` ### Consulta de transação [](#consulta-de-transação) ``` $response = Mpesa::transaction($transactionReference, $thirdPartyReference); ``` ParâmetroTipoDescrição`$transactionReference``string`A referência (`input_QueryReference`) da transação a consultar.`$thirdPartyReference``string`Mesma `thirdPartyReference` usada na transação original.### Reversão [](#reversão) ``` $response = Mpesa::reversal($amount, $transactionID, $thirdPartyReference); ``` ParâmetroTipoDescrição`$amount``float`Valor a reverter.`$transactionID``string`ID interno M-Pesa da transação original (`output_TransactionID`).`$thirdPartyReference``string`Referência única do lado do *third party*.> Exige `MPESA_INITIATOR_IDENTIFIER` e `MPESA_SECURITY_CREDENTIAL` configurados. O objecto `Transaction` ----------------------- [](#o-objecto-transaction) Todos os métodos devolvem uma instância de `BrilliantMind\MPesa\Transaction`. Métodos disponíveis: ``` $tx->getResponseCode(); // 'INS-0', 'INS-6', ... $tx->getStatusCode(); // int — equivalente HTTP (200, 400, 500, ...) $tx->getMessage(); // descrição associada ao código INS-* $tx->getDescription(); // descrição vinda da API M-Pesa (output_ResponseDesc) $tx->getTransactionID(); // ID interno M-Pesa $tx->getConversationID(); // ID de conversação $tx->getThirdPartReference(); // o teu thirdPartyReference $tx->toArray(); // array normalizado $tx->toJson(); // string JSON $tx->jsonSerialize(); // suporte a json_encode() $tx->responseCode; // acesso mágico aos campos do toArray() ``` Exemplo de tratamento: ``` $tx = Mpesa::c2b(100.0, '258846000000', $ref, $thirdPartyRef); if ($tx->getResponseCode() === 'INS-0') { // sucesso — guarda $tx->getTransactionID() em DB } else { Log::warning('M-Pesa falhou', $tx->toArray()); } ``` Códigos de resposta ------------------- [](#códigos-de-resposta) A SDK conhece 33 códigos `INS-*` documentados pela M-Pesa, com o equivalente HTTP e descrição. Lista parcial: CódigoHTTPSignificado`INS-0`200Request processed successfully`INS-1`500Internal Error`INS-2`401Invalid API Key`INS-5`400Transaction cancelled by customer`INS-6`400Transaction Failed`INS-9`408Request timeout`INS-10`400Duplicate Transaction`INS-13`400Invalid Shortcode Used`INS-15`400Invalid Amount Used`INS-17`400Invalid Transaction Reference (length 1–20)`INS-20`400Not All Parameters Provided`INS-21`400Parameter validations failed`INS-26`401Not authorised`INS-996`400Customer Account Status Not Active`INS-2006`400Insufficient balance`INS-2051`400Invalid MSISDN`INS-2057`400MSISDN is not registeredLista completa em [src/Response.php](src/Response.php). Para códigos desconhecidos, `Response::describe()` devolve `['code' => 0, 'message' => 'Unknown response code']` em vez de rebentar. Modo fake (testes) ------------------ [](#modo-fake-testes) Útil para testes unitários — não faz chamadas HTTP, devolve `Transaction` canónicas: ``` use BrilliantMind\MPesa\MPesa; $mpesa = app('mpesa'); // ou: resolve(MPesa::class) $mpesa->fake(200); // sucesso (INS-0) $tx = $mpesa->c2b(100.0, '258840000000', 'REF', 'PARTY'); // $tx->getStatusCode() === 200 // $tx->getResponseCode() === 'INS-0' // $tx->getTransactionID() começa por 'FAKE-' ``` Cenários de erro: ``` $mpesa->fake(400, 'Saldo insuficiente'); $tx = $mpesa->c2b(...); // $tx->getStatusCode() === 400 // $tx->getDescription() === 'Saldo insuficiente' ``` Ajustar a meio da sessão: ``` $mpesa->setResponseCode(401); $mpesa->setStatus('Token inválido'); ``` O facade `Mpesa::fake(...)` também funciona porque a facade proxia métodos ao singleton. Ver [teste.php](teste.php) na raiz para um runner manual end-to-end. Requisitos ---------- [](#requisitos) - PHP `^8.1` - Laravel 10, 11 ou 12 - Extensões: `openssl`, `json`, `curl` Notas sobre portos M-Pesa ------------------------- [](#notas-sobre-portos-m-pesa) A API M-Pesa Moçambique usa portos diferentes por operação: OperaçãoPortoEndpointC2B`18352``/ipg/v1x/c2bPayment/singleStage/`B2C`18345``/ipg/v1x/b2cPayment/`B2B`18349``/ipg/v1x/b2bPayment/`Query`18353``/ipg/v1x/queryTransactionStatus/`Reversal`18354``/ipg/v1x/reversal/`A SDK trata desta dispersão internamente — não é preciso configurar portos no `.env`. ### Health Score 42 — FairBetter than 88% of packages Maintenance86 Actively maintained with recent releases Popularity18 Limited adoption so far Community9 Small or concentrated contributor base Maturity45 Maturing project, gaining track record Bus Factor1 Top contributor holds 57.9% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~3 days Total 2 Last Release 122d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/77959590?v=4)[Osvaldo Geraldo Manjate](/maintainers/osvaldogeraldo)[@osvaldogeraldo](https://github.com/osvaldogeraldo) --- Top Contributors [![osvaldogeraldo](https://avatars.githubusercontent.com/u/77959590?v=4)](https://github.com/osvaldogeraldo "osvaldogeraldo (11 commits)")[![paulo-maculuve](https://avatars.githubusercontent.com/u/75036310?v=4)](https://github.com/paulo-maculuve "paulo-maculuve (6 commits)")[![HelioHerculano](https://avatars.githubusercontent.com/u/66783101?v=4)](https://github.com/HelioHerculano "HelioHerculano (2 commits)") --- Tags laravelmpesamozambiquebrilliant\_mind ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/brilliant-mind-m-pesa/health.svg) ``` [![Health](https://phpackages.com/badges/brilliant-mind-m-pesa/health.svg)](https://phpackages.com/packages/brilliant-mind-m-pesa) ``` ### Alternatives [craftcms/cms Craft CMS 3.6k3.6M3.1k](/packages/craftcms-cms)[sebdesign/laravel-viva-payments A Laravel package for integrating the Viva Payments gateway 4851.0k](/packages/sebdesign-laravel-viva-payments)[simplestats-io/laravel-client Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof. 5021.9k](/packages/simplestats-io-laravel-client)[iankumu/mpesa A package that helps integrate the Mpesa APIs to your Laravel Project 5220.0k](/packages/iankumu-mpesa) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)