README

MPesa Laravel SDK

Laravel MPESA SDK é como o próprio nome diz um SDK para pagamentos Online Via MPESA.

A partir deste SDK é possivel comunicar com o Open-api e executar operações de coleta de valores, transferencias, pesquisa e outras possibilidadades disponibilizadas pelo Mpesa.

Instalação

O método de instalação mais basico é usando o gestor de dependências Composer. Que na verdade eu recomendo.

composer require samuelbie/mpesa

Ou por outra basta adicionar ao suas dependencias(composer.json):

"samuelbie/mpesa": "^1.5",

e depois executar o comando:

composer update

Configuração

Todas as suas configurações estarão guardas no ficheiro interno de configuração mpesa.php com o aspecto:

<?php
return [
    /*
    |--------------------------------------------------------------------------
    | API host of M-Pesa API
    |--------------------------------------------------------------------------
    |
    | Here you may specify the API host provided by Vodacom for API operations
    |
    */
    'api_host'              => env('MPESA_API_HOST', 'api.sandbox.vm.co.mz'),

    /*
    |--------------------------------------------------------------------------
    | Public key for use in M-Pesa API
    |--------------------------------------------------------------------------
    |
    | Here you may specify the public key provided by Vodacom to you
    |
    */
    'public_key'            => env('MPESA_PUBLIC_KEY'),
    /*
    |--------------------------------------------------------------------------
    | API Key of M-Pesa API
    |--------------------------------------------------------------------------
    |
    | Here you may specify the API key provided by Vodacom to you
    |
    */
    'api_key'               => env('MPESA_API_KEY'),

    /*
    |--------------------------------------------------------------------------
    | Origin of M-Pesa API
    |--------------------------------------------------------------------------
    |
    |
    */
    'origin'                => env('MPESA_ORIGIN', '*'),

    'verifySSL'             => false,

    /*
    |--------------------------------------------------------------------------
    | Service Provider Code of M-Pesa API
    |--------------------------------------------------------------------------
    |
    | Here you may specify the service provider code of M-Pesa provided by Vodacom to you
    |
    */
    'service_provider_code' => env('MPESA_PROVIDER_NUMBER', '171717'),

    /*
    |--------------------------------------------------------------------------
    | Initiator Identifier of M-Pesa API
    |--------------------------------------------------------------------------
    |
    | Here you may the initiator identifier provided by Vodacom to you
    |
    */
    'initiator_identifier'  => env('MPESA_INITIATOR_IDENTIFIER'),

    /*
    |--------------------------------------------------------------------------
    | Security credential of M-Pesa API
    |--------------------------------------------------------------------------
    |
    | Here you may specify the security credential provided by Vodacom to you
    |
    */
    'security_credential'   => env('MPESA_SECURITY_CREDENTIAL'),


    "c2b_endpoint"          => env('MPESA_C2B_ENDPOINT', ':18352/ipg/v1x/c2bPayment/singleStage/'),
    "b2c_endpoint"          => env('MPESA_B2C_ENDPOINT', ':18345/ipg/v1x/b2cPayment/'),
    "query_endpoint"        => env('MPESA_Query_ENDPOINT', ':18353/ipg/v1x/queryTransactionStatus/'),
    "reversal_endpoint"     => env('MPESA_Reversal_ENDPOINT', ':18354/ipg/v1x/reversal/'),

    "c2b_method"        => env('MPESA_C2B_METHOD', "POST"),
    "b2c_method"        => env('MPESA_B2C_METHOD', "POST"),
    "query_method"      => env('MPESA_Query_METHOD', "GET"),
    "reversal_method"   => env('MPESA_Reversal_METHOD', "PUT"),
];

Neste caso o passar todas as suas credenciais locais ou de produção no seu ficheiro .env anexe as seguintes chaves.

MPESA_API_HOST='api.vm.co.mz' #ou api.sandbox.vm.co.mz
MPESA_API_KEY = 'api Key'
MPESA_PUBLIC_KEY = 'Chave Pubica='
MPESA_PROVIDER_NUMBER='171700'
MPESA_ORIGIN='*'
MPESA_INITIATOR_IDENTIFIER='JMhMnVM3dddddRMA3'
MPESA_SECURITY_CREDENTIAL='Sp0ng3dddd'

Utilização

Métodos disponíveis

Coleta (C2B)

Assinatura

/**
* Initiates a C2B transaction on the M-Pesa API.
* @param float $amount Valor
* @param string $msisdn numero de telefone (Ex: 847386187 / +258850233654)
* @param string $reference Referencia da transação. Ex: Compra de Modem 3G
* @param string $third_party_reference  Referencia única da transação. Ex: 1285GVHss
* @return TransactionResponseInterface
* @throws Exception
 */
public function c2b(float $amount, string $msisdn, string $reference, string $third_party_reference): TransactionResponseInterface

Exemplo

use Samuelbie\Mpesa\Transaction;
$mpesa = new Transaction();
$response = $mpesa->c2b('10','258845968745', 'reference' ,'unique_reference');

Transferencia para cliente (B2C)

Signature

/**
 * Initiates a B2C transaction on the M-Pesa API.
 * @param float $amount Valor
 * @param string $msisdn numero de telefone (Ex: 847386187 / +258850233654)
 * @param string $reference Referencia da transação. Ex: Pagamento de comissão de venda
 * @param string $third_party_reference  Referencia única da transação. Ex: 1285GVHss
 * @return TransactionResponseInterface
 * @throws Exception
 */
public function b2c(float $amount, string $msisdn, string $reference, string $third_party_reference): TransactionResponseInterface

Exemplo

use Samuelbie\Mpesa\Transaction;
$mpesa = new Transaction();
$response = $mpesa->b2c('10','258845968745', 'Comissao' ,'unique_reference');

Transferencia para Entidade (B2B)

Reverção (Reversal)

Assinatura

    /**
     * Initiates a Reversal transaction on the M-Pesa API.
     * @param float $amount Valor a ser revertido
     * @param string $transaction_id ID Transação que precisa ser revertida
     * @param string $third_party_reference  Referencia única da transação. Ex: 1285GVHss
     * @return TransactionResponseInterface
    */
    public function reversal(
        float $amount,
        string $transaction_id,
        string $third_party_reference
    ): TransactionResponseInterface

Exemplo

use Samuelbie\Mpesa\Transaction;
$mpesa = new Transaction();
$response = $mpesa->reversal(10,'ACK19SSS', 'Agua2020');

Consulta de estado (Query Transaction Status)

/**
 * Initiates a transaction Query on the M-Pesa API.
 * @param string $query_reference Transaction id/ Conversation ID (Gerado pelo MPesa)
 * @param string $third_party_reference  Referencia única da transação (Gerado pelo sistema de terceiro). Ex: 1285GVHss
 * @return TransactionResponseInterface
*/
public function query(string $query_reference, string $third_party_reference): TransactionResponseInterface

Exemplo

use Samuelbie\Mpesa\Transaction;
$mpesa = new Transaction();
$response = $mpesa->query('56b97c7a59dd40738843ca7234796c4d', 'Agua2020');

Resultados

Todas as operações de ou métodos disponiveis retornam um objecto de TransactionResponseInterface, esta interface ordena que os que a implementam, implementem os métodos:

    /**
     * Returns the Response Code
     *
     * @return string
     */
    public function getCode(): string;

    /**
     * Returns the response description
     *
     * @return string
     */
    public function getDescription(): string;

    /**
     * Returns the TransactionID
     *
     * @return string
     */
    public function getTransactionID(): string;

    /**
     * Returns the Conversation ID
     *
     * @return string
     */
    public function getConversationID(): string;

    /**
     * Returns the Transaction Status from Query API
     *
     * @return string
     */
    public function getTransactionStatus(): string;

    /**
     * Returns the raw response from M-Pesa API
     *
     * @return string
     */
    public function getResponse(): string;

    /**
     * Returns the Response Code
     * @return string
     */
    public function getStatusCode(): string;


    /**
     * Returns the JSON response from M-Pesa API
     * @return string
     */
    public function getBody();

Recomendações

É recomendado que que acima de tudo o usuário desta biblioteca leia a documentação do Open-Api e entenda o principio de funcionamento desta, para que possa entender os códigos de respostas, e as mensagens.

Contributo

Desde ja queremos agradecer aos criadores do pacote para PHP abdulmueid\mpesa, uma vez que este pacote é uma adaptação do pacote por eles criados. Aqui vai meu Kanimanbo a vocês

Vulnerabilidades de Segurança

Se descobrires alguma vulnerabilidade neste pacote, por favor envie um email para Samuel Bié via samuel.bie75@gmail.com. Todas as falhas de segurança serão devidamente analizadas e tratadas.

Licença

Mpesa Laravel SDK é de codigo livre sob licença MIT license.

⚡ Abraços ⚡