PHP code example of grupofixit / mpesa

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

grupofixit / mpesa example snippets

use GrupoFixIT\Mpesa\MpesaClient;
use GrupoFixIT\Mpesa\Config\MpesaConfig;
use GrupoFixIT\Mpesa\Config\Credentials;
use GrupoFixIT\Mpesa\Enums\Environment;

$config = new MpesaConfig(
    environment: Environment::Sandbox, // ou Environment::Live
    credentials: new Credentials(
        apiKey: 'sua-api-key',
        publicKey: 'sua-chave-publica-rsa-ou-pem',
        serviceProviderCode: '171717',
        initiatorIdentifier: 'IdentificadorOpcionalParaReversal',
        securityCredential: 'SenhaCifradaOpcionalParaReversal'
    ),
    timeout: 30.0,
);

$mpesa = MpesaClient::create($config);

use GrupoFixIT\Mpesa\Requests\C2BRequest;
use GrupoFixIT\Mpesa\Support\Money;
use GrupoFixIT\Mpesa\Support\Msisdn;
use GrupoFixIT\Mpesa\Support\Reference;
use GrupoFixIT\Mpesa\Exceptions\OutcomeUnknownException;
use GrupoFixIT\Mpesa\Exceptions\ApiException;

try {
    $request = new C2BRequest(
        transactionReference: Reference::generate(12, 'TRX'), // Máx. 20 caracteres
        customerMsisdn: Msisdn::from('258841234567'), // 84 ou 85 (12 dígitos)
        amount: Money::mzn('150.00'), // Decimal protegido
        thirdPartyReference: Reference::generate(12, 'REF')
    );

    $result = $mpesa->c2b($request);

    if ($result->isSuccess()) {
        echo "Pedido aceite pela Vodacom. Conversation ID: " . $result->conversationId;
        // Agendar verificação via Status Query
    }
} catch (OutcomeUnknownException $e) {
    // REGRA DE OURO: OCORREU TIMEOUT / FALHA DE REDE. NUNCA REENVIE O C2B!
    // Consulte o estado da transação usando o thirdPartyReference retornado:
    $ref = $e->getThirdPartyReference();
    // Agendar job de Status Query
} catch (ApiException $e) {
    echo "Erro retornado pela Vodacom: " . $e->getMessage();
}

use GrupoFixIT\Mpesa\Requests\TransactionStatusRequest;

$request = new TransactionStatusRequest(
    thirdPartyReference: 'REF_ORIGINAL',
    queryReference: 'CONVERSATION_ID_OU_TRANSACTION_ID'
);

$statusResult = $mpesa->transactionStatus($request);

if ($statusResult->isSuccess()) {
    echo "Estado da transação: " . $statusResult->transactionStatus->value; // Completed, Failed, Pending...
    if ($statusResult->transactionStatus->isTerminal()) {
        // Atualizar base de dados com estado final
    }
}

use GrupoFixIT\Mpesa\Requests\CustomerNameRequest;
use GrupoFixIT\Mpesa\Support\Msisdn;
use GrupoFixIT\Mpesa\Support\Reference;

$request = new CustomerNameRequest(
    customerMsisdn: Msisdn::from('258841234567'),
    thirdPartyReference: Reference::generate()
);

$nameResult = $mpesa->customerName($request);

if ($nameResult->isSuccess()) {
    echo "Nome do Cliente: " . $nameResult->customerName; // Ex: Jo** Sil**
}

use GrupoFixIT\Mpesa\Requests\B2CRequest;
use GrupoFixIT\Mpesa\Requests\B2BRequest;

// B2C
$b2cResult = $mpesa->b2c(new B2CRequest(
    customerMsisdn: Msisdn::from('258841234567'),
    amount: Money::mzn('250.00'),
    transactionReference: Reference::generate(),
    thirdPartyReference: Reference::generate()
));

// B2B
$b2bResult = $mpesa->b2b(new B2BRequest(
    transactionReference: Reference::generate(),
    amount: Money::mzn('5000.00'),
    thirdPartyReference: Reference::generate(),
    receiverPartyCode: '979797' // Shortcode da empresa destinatária
));

use GrupoFixIT\Mpesa\Requests\ReversalRequest;
use GrupoFixIT\Mpesa\Support\Money;
use GrupoFixIT\Mpesa\Support\Reference;

$reversalResult = $mpesa->reversal(new ReversalRequest(
    transactionId: 'ORIGINAL_TRANSACTION_ID',
    thirdPartyReference: Reference::generate(),
    reversalAmount: Money::mzn('50.00') // Opcional para estorno parcial; se omitido, estorna o total
));

// No seu controlador de webhook
$rawJson = file_get_contents('php://input');

// 1. Fazer o parse seguro
$callbackPayload = $mpesa->parseCallback($rawJson);

// 2. Gerar a resposta de confirmação no formato oficial exigido pela Vodacom
$acknowledgement = $mpesa->acknowledgeCallback($callbackPayload);

header('Content-Type: application/json');
echo json_encode($acknowledgement->toArray());

// 3. Regra de Ouro: Agendar Status Query para confirmar o estado antes de alterar saldos

use GrupoFixIT\Mpesa\Testing\FakeMpesa;

$fake = FakeMpesa::create();

// Simular sucesso no C2B
$fake->fakeC2BSuccess('CONV_123', 'TRX_999', 'REF_001');

$client = $fake->getClient();
$res = $client->c2b($request);

$this->assertTrue($res->isSuccess());
$this->assertSame('CONV_123', $res->conversationId);