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.

Feito para funcionar no Laravel sem configuração manual: instala, coloca duas variáveis no .env e já podes cobrar.

Índice

• Instalação
• Configuração
  • Variáveis de ambiente
  • Tabela completa de variáveis
  • Publicar o ficheiro de configuração
• Utilização
  • C2B — cliente paga à empresa
  • B2C — empresa paga ao cliente
  • B2B — empresa paga a outra empresa
  • Consulta de transação
  • Reversão
• O objecto Transaction
• Códigos de resposta
• Modo fake (testes)
• Erros
• Fora do Laravel
• Notas sobre portos M-Pesa
• Requisitos

Instalação

composer require brilliant_mind/m-pesa

É tudo. O pacote usa package auto-discovery do Laravel — o ServiceProvider e os aliases MPesa e Mpesa são registados automaticamente. Não precisas de publicar o config, nem de editar config/app.php, bootstrap/providers.php ou o AppServiceProvider.

Configuração

Variáveis de ambiente

Só MPESA_API_KEY e MPESA_PUBLIC_KEY são obrigatórias. Tudo o resto tem valores por omissão prontos para o sandbox.

Desenvolvimento (sandbox)

# MPESA DEVELOPMENT
MPESA_API_KEY=sua_api_key_sandbox
MPESA_PUBLIC_KEY="MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB...FwIDAQAB"
MPESA_ENVIRONMENT=development
MPESA_SERVICE_PROVIDER_CODE=171717

Produção

# MPESA PRODUCTION
MPESA_API_KEY=sua_api_key_producao
MPESA_PUBLIC_KEY="MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB...FwIDAQAB"
MPESA_ENVIRONMENT=production
MPESA_SERVICE_PROVIDER_CODE=903153
MPESA_INITIATOR_IDENTIFIER=seu_initiator
MPESA_SECURITY_CREDENTIAL=seu_credential_encriptado

A chave pública é uma linha longa de base64 — envolve-a em aspas duplas. É aceite em qualquer formato: uma linha, com quebras de linha, ou o bloco PEM completo. Se preferires guardá-la num ficheiro, deixa MPESA_PUBLIC_KEY vazia e usa MPESA_PUBLIC_KEY_PATH.

Nota: MPESA_ENV continua a ser aceite como alias retrocompatível de MPESA_ENVIRONMENT.

Se mudaste o .env e nada aconteceu, limpa a cache: php artisan config:clear.

Tabela completa de variáveis

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

Utilização

As operações existem em duas formas, ambas suportadas:

// Estática — como na v1.x
use BrilliantMind\MPesa\MPesa;

$transaction = MPesa::c2b(100, '841234567', 'ENC0001', 'TPR0001');

// De instância — via container, injecção de dependências ou facade
$transaction = app('mpesa')->c2b(100, '841234567', 'ENC0001', 'TPR0001');

A facade está disponível globalmente, sem use, em qualquer das grafias (MPesa ou Mpesa):

$transaction = MPesa::c2b(
    amount: 100,
    msisdn: '841234567',
    transactionReference: 'ENC0001',
    thirdPartyReference: 'TPR0001',
);

if ($transaction->isSuccessful()) {
    // guardar $transaction->getTransactionID()
}

return $transaction->getMessage();

O número de telemóvel é normalizado automaticamente — 841234567, 0841234567, +258 84 123 4567 e 258841234567 produzem todos 258841234567.

C2B — cliente paga à empresa

Debita a carteira do cliente e credita a da empresa. A M-Pesa envia um USSD Push ao cliente para confirmar o PIN.

$transaction = MPesa::c2b(100, '841234567', 'ENC0001', 'TPR0001');

B2C — empresa paga ao cliente

$transaction = MPesa::b2c(100, '841234567', 'ENC0002', 'TPR0002');

B2B — empresa paga a outra empresa

O segundo argumento é o shortcode da empresa que recebe, não um número de telemóvel.

$transaction = MPesa::b2b(100, '979797', 'ENC0003', 'TPR0003');

Consulta de transação

$transaction = MPesa::transaction('ENC0001', 'TPR0001');

$transaction->getTransactionStatus(); // ex.: 'Completed'

Reversão

Requer MPESA_INITIATOR_IDENTIFIER e MPESA_SECURITY_CREDENTIAL.

$transaction = MPesa::reversal(100, '49XCDF6', 'TPR0001');

O objecto Transaction

$transaction->isSuccessful();          // bool — true quando o código é INS-0
$transaction->failed();                // bool
$transaction->getResponseCode();       // 'INS-0'
$transaction->getMessage();            // descrição legível
$transaction->getTransactionID();      // id da transacção na M-Pesa
$transaction->getConversationID();
$transaction->getThirdPartReference();
$transaction->getTransactionStatus();  // só na consulta de estado
$transaction->getHttpStatus();         // HTTP devolvido pelo gateway
$transaction->getStatusCode();         // HTTP equivalente ao código INS
$transaction->raw();                   // payload original da M-Pesa
$transaction->toArray();
$transaction->toJson();

Nunca lança excepção por a M-Pesa ter recusado a transacção: uma recusa é sempre um Transaction com failed() === true. Excepções ficam reservadas para erros de configuração e de rede (ver Erros).

Códigos de resposta

A tabela completa de códigos INS está em BrilliantMind\MPesa\Response::$codes:

use BrilliantMind\MPesa\Response;

Response::message('INS-2006');   // 'Insufficient balance'
Response::status('INS-2006');    // 422
Response::describe('INS-2006');  // ['code' => 422, 'message' => 'Insufficient balance']
Response::isSuccessful('INS-0'); // true

Modo fake (testes)

Nos teus testes usa fake() para não tocar na rede:

use BrilliantMind\MPesa\MPesa;

MPesa::fake();                       // devolve sempre INS-0
MPesa::fake(422, 'INS-2006');        // simula saldo insuficiente
MPesa::fakeWith([                    // controlo total do payload
    'output_ResponseCode' => 'INS-0',
    'output_TransactionID' => '49XCDF6',
]);

MPesa::c2b(100, '841234567', 'REF', 'TPR');

MPesa::recorded();  // pedidos capturados, para asserções
MPesa::stopFaking();

Erros

Todas herdam de BrilliantMind\MPesa\Exceptions\MPesaException, por isso podes apanhar tudo de uma vez:

use BrilliantMind\MPesa\Exceptions\MPesaException;

try {
    $transaction = MPesa::c2b(100, $msisdn, $reference, $thirdPartyReference);
} catch (MPesaException $e) {
    report($e);
}

Fora do Laravel

O pacote também funciona em PHP puro; basta configurá-lo à mão:

require __DIR__ . '/vendor/autoload.php';

use BrilliantMind\MPesa\MPesa;

MPesa::config(
    api_key: 'a-tua-api-key',
    public_key: 'a-tua-public-key',
    environment: 'development',
    service_provider_code: '171717',
);

$transaction = MPesa::c2b(100, '841234567', 'ENC0001', 'TPR0001');

MPesa::config() aceita argumentos parciais — o que não passares mantém o valor actual.

Notas sobre portos M-Pesa

O gateway escuta num porto diferente por operação e a SDK trata disso sozinha:

Como não são portos padrão, muitos alojamentos partilhados bloqueiam o tráfego de saída para eles — é a causa mais comum de ConnectionException. Se precisares de forçar um porto único (proxy, por exemplo), define MPESA_PORT.

Requisitos

• PHP ^8.1
• Extensões openssl, json, curl
• Laravel 10, 11 ou 12 (opcional)