README

SDK para interagir com a API M-Pesa Moçambique: C2B, B2B, B2C, consulta de transação e reversão.

Índice

• Instalação
• Configuração
  • Variáveis de ambiente
  • Tabela completa de variáveis
  • Publicar o ficheiro de configuração
• Utilização
  • C2B, B2B, B2C
  • Consulta de transação
  • Reversão
• O objecto Transaction
• Códigos de resposta
• Modo fake (testes)
• Requisitos
• Notas sobre portos M-Pesa

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

Variáveis de ambiente

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

# 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

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)

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)

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) e estão hardcoded na SDK. Se vires config('services.mpesa.port') em código antigo, pode ser removido.

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

$response = Mpesa::c2b($amount, $msisdn, $transactionReference, $thirdPartyReference);

B2C — Empresa para Cliente

$response = Mpesa::b2c($amount, $msisdn, $transactionReference, $thirdPartyReference);

B2B — Empresa para Empresa

$response = Mpesa::b2b($amount, $msisdn, $transactionReference, $thirdPartyReference);

Consulta de transação

$response = Mpesa::transaction($transactionReference, $thirdPartyReference);

Reversão

$response = Mpesa::reversal($amount, $transactionID, $thirdPartyReference);

Exige MPESA_INITIATOR_IDENTIFIER e MPESA_SECURITY_CREDENTIAL configurados.

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

A SDK conhece 33 códigos INS-* documentados pela M-Pesa, com o equivalente HTTP e descrição. Lista parcial:

Lista completa em src/Response.php. Para códigos desconhecidos, Response::describe() devolve ['code' => 0, 'message' => 'Unknown response code'] em vez de rebentar.

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 na raiz para um runner manual end-to-end.

Requisitos

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

Notas sobre portos M-Pesa

A API M-Pesa Moçambique usa portos diferentes por operação:

A SDK trata desta dispersão internamente — não é preciso configurar portos no .env.