README

简介

封装mpesa API的PHP库

入门

此库在以下环境中运行

PHP ^7.4
PHP ^8.0

安装

您可以通过composer安装此包：composer require hackdelta/mpesa

使用

要检查最近的变化，请查看变更日志

此包的目的是封装Mpesa API，以便提供更简单、更整洁的方法。此库在内部使用Guzzle http库进行http请求。

此文档将分为五个部分，涵盖特定区域。欢迎提出任何其他附加注释。请随时贡献。

库简介
C2B交易
B2B交易
B2C交易
通用交易

有关此处未提及的进一步详细信息，请查看

初始化库

此库要求传递一个配置，该配置将在库的各个部分中使用

use Hackdelta\Mpesa\Mpesa;
use Hackdelta\Mpesa\Main\MpesaConfig;
use Hackdelta\Mpesa\Extras\MpesaConstants;

$config = new MpesaConfig(
      [
         // API Credentials
         'consumer_key'    => 'YOUR_CONSUMER_KEY',
         'consumer_secret' => 'YOUR_CONSUMER_SECRET',

         // Environment
         'environment' => 'sandbox', // on sandbox environment
         // 'environment' => 'production', // on production

         // User credential
         'initiator_name'     => 'INITIATOR_NAME',
         'initiator_password' => 'INITIATOR_PASSWORD',

         // Or
         'security_credential' => '',

         // Used in combination with initiator name
         // and password
         // If you have different mpesa cert paths you can set them here 
         'sandbox_certificate_path'    => '',
         'production_certificate_path' => '',

         // Lipa na mpesa online passkey
         // For STK push
         'passkey' => 'PASSKEY',

         // Short code
         'short_code'          => 'SHORT_CODE', // This is your till or paybill
         'business_short_code' => 'BUSINESS_SHORT_CODE', // This is your head office number which for
                                                         // paybills it's the same, leave this blank
                                                         // if you are using paybill

         // Identifier type of the shortcode
         'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_PAYBILL, // For paybills
         // 'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_TILL, // For till

         // URLS
         // Webhook URLS
         'confirmation_url' => 'https://domain.example/confirm.php', // Where confirmation
                                                                     // callbacks will hit
         'validation_url'   => 'https://domain.example/validate.php',

         // STK callback URL
         'stk_callback_url' => 'https://domain.example/callback.php',

         // Query results URL
         'queue_timeout_url' => 'https://domain.example/callback.php',
         'result_url'        => 'https://domain.example/callback.php',

         // Pull request
         'organization_msisdn' => '0722000000', // Used for pull requests, this is the
                                                // number that receives confirmation messages
         'pull_callback_url'   => 'https://domain.example/callback.php',
      ]
   );

$mpesa = new Mpesa($config);

您不必设置所有这些配置，这里只是列出您可用的所有配置选项。

编辑配置

初始化后，每个类都提供了在运行时编辑配置类的方式

例如

use Hackdelta\Mpesa\Mpesa;
use Hackdelta\Mpesa\Main\MpesaConfig;

$config = new MpesaConfig(...); // Remember to pass in the configurations here
$mpesa = new Mpesa($config);

$mpesa->getConfig()
      ->setSandboxEnvironment(false) // Change environment to production, true means sandbox
      ...
      ->setConsumerKey('new consumer key');

请注意，set方法可以链式调用。

有关可用方法的完整列表，请查看规范

整个库的示例用法

这只是一个典型场景的概述，可能用于测试目的，在此示例中，我们使用测试凭据，但是您必须提供所有回调URL、消费者密钥、消费者密钥和您的手机号码进行STK推送测试。您可以从Safaricom开发者门户获取测试凭据注意：由于B2B、C2B的不同短码，某些测试可能会失败，简而言之，B2B、C2B、撤销和拉取交易请求应失败

use Hackdelta\Mpesa\Mpesa;
use Hackdelta\Mpesa\Main\MpesaConfig;
use Hackdelta\Mpesa\Extras\MpesaConstants;
use Hackdelta\Mpesa\Exceptions\MpesaInternalException;
use Hackdelta\Mpesa\Exceptions\MpesaClientExceptions;
use Hackdelta\Mpesa\Exceptions\MpesaServerException;

$config = [
   // API Credentials
   'consumer_key'    => 'YOUR_CONSUMER_KEY', // <--- Change this
   'consumer_secret' => 'YOUR_CONSUMER_SECRET', // <--- Change this

   // Environment
   'environment' => 'sandbox', // on sandbox environment
   // 'environment' => 'production', // on production

   // User credential
   'initiator_name'     => 'testAPI497',
   'initiator_password' => 'Safaricom111!',

   // Lipa na mpesa online passkey
   // For STK push
   'passkey' => 'bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919',

   // Short code
   'short_code'          => '601497', // This is your till or paybill
   'business_short_code' => '601497', // This is your head office number which for
                                                   // paybills it's the same, leave this blank
                                                   // if you are using paybill

   // Identifier type of the shortcode
   'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_PAYBILL, // For paybills
   // 'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_TILL, // For till

   // URLS
   // Webhook URLS
   'confirmation_url' => 'https://domain.example.com/confirm.php', // Where confirmation
                                                               // callbacks will hit
   'validation_url'   => 'https://domain.example.com/validate.php',

   // STK callback URL
   'stk_callback_url' => 'https://domain.example.com/callback.php',

   // Query results URL
   'queue_timeout_url' => 'https://domain.example.com/callback.php',
   'result_url'        => 'https://domain.example.com/callback.php',

   // Pull request
   'organization_msisdn' => '0722000000', // Used for pull requests, this is the
                                          // number that receives confirmation messages
   'pull_callback_url'   => 'https://domain.example.com/callback.php',

];

$mpesa = new Mpesa($config);

// Check internal
function test_getting_auth_token() {
   echo $mpesa->getConfig()->getToken();
}

// C2B
function test_registering_c2b_callbacks() {
   echo $mpesa->registerURL();
}

function test_simulating_transaction() {
   echo $mpesa->simulate('254708374149', 100, 'test account reference');
}

function test_initiating_stk_push() {
   $mpesa->getConfig()
         ->setShortcode("short_code", '174379')
         ->setBusinessShortCode("business_short_code", '174379');
   
   // Change "254700000000" to your phone number
   echo $mpesa->STKPush("254700000000", 1, "Test", "Test");

   // Reset config back
   $mpesa->getConfig()
         ->setShortcode("short_code", '601497')
         ->setBusinessShortCode("business_short_code", '601497');
   
}

function test_getting_Stk_push_status() {
   $mpesa->getConfig()
         ->setConfig("short_code", '174379')
         ->setConfig("business_short_code", '174379');

   // Change the checkout id to the one you git from running the above
   echo $mpesa->STKPushQuery("ws_CO_030520210342393444");

   // Reset config back
   $mpesa->getConfig()
         ->setConfig("short_code", '601497')
         ->setConfig("business_short_code", '601497');
}

// General
function test_getting_balance() {
   echo $mpesa->checkBalance();
}

function test_reversal() {
   // Change 'PE341HJ3Q8' to a test value gotten after simulating the transaction
   echo $mpesa->reverseTransaction('PE341HJ3Q8', 100, '2547000000000',                       MpesaConstants::MPESA_IDENTIFIER_TYPE_MSISDN);

}

function test_checking_transaction_Status() {
   echo $mpesa->checkTransactionStatus('PE341HJ3Q8');
}

function test_register_pull_url() {
   echo $mpesa->pullRequestRegisterURL();
}

function test_pull() {
   echo $mpesa->pullRequestQuery("2019-07-31 20:00:00", "2019-07-31 22:00:00");
}

// B2C
function test_B2C() {
   echo $mpesa->sendB2C(
        100, 
        '254700000000',
        MpesaConstants::MPESA_COMMAND_ID_SALARY_PAYMENT 
    );
}

// B2B
function test_B2B() {
   echo $mpesa->sendB2B(
        10, 
        '600000',
        MpesaConstants::MPESA_COMMAND_ID_BUSINESS_PAY_BILL,
        MpesaConstants::MPESA_IDENTIFIER_TYPE_PAYBILL,
        "account" 
    );
}

// In order to run the test uncomment one or more of the following
try {

   /**
    * This tests should pass provided you've set the correct configurations
   */

   /* Pre request check */
   test_getting_auth_token();

   /* C2B */
   // test_registering_c2b_callbacks();
   // test_simulating_transaction();
   // test_initiating_stk_push();
   // test_getting_Stk_push_status();

   /* B2B */
   // test_B2B(); // Expected to fail on sandbox

   /* B2C */
   // test_B2C(); // Expected to fail on sandbox

   /* General */
   // test_getting_balance();
   // test_checking_transaction_Status();
   // test_reversal(); // Expected to fail on sandbox
   // test_register_pull_url(); // Expected to fail on sandbox
   // test_pull(); // Expected to fail on sandbox

} catch(MpesaInternalException $e) {
   // This exception occurs when a configuration is missing e.g. consumer key
   echo $e->getMessage();

} catch(MpesaClientException $ce){
   // This occurs when the request has been sent to the mpesa servers but some invalid
   // data was supplied e.g. invalid consumer key
   
   echo $ce->getStatusCode(); // Returns http status code of the error
   echo $ce->getMessage(); // Returns the error message
   echo $ce->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($ce->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

} catch (MpesaServerException $se) {
   // This occurs when the request has been sent to the mpesa servers
   // but the server experienced some issues this is an error from the gateway and
   // is not the client fault

   echo $se->getStatusCode(); // Returns http status code of the error
   echo $se->getMessage(); // Returns the error message
   echo $se->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($se->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method
}

注册验证和确认URL（C2B）

要注册确认和验证URL，您需要设置以下配置

注意：此操作只能在生产环境中执行一次*

use Hackdelta\Mpesa\Mpesa;
use Hackdelta\Mpesa\Main\MpesaConfig;
use Hackdelta\Mpesa\Extras\MpesaConstants;
use Hackdelta\Mpesa\Exceptions\MpesaInternalException;
use Hackdelta\Mpesa\Exceptions\MpesaClientExceptions;
use Hackdelta\Mpesa\Exceptions\MpesaServerException;

$config = new MpesaConfig(
      [
         // API Credentials
         'consumer_key'    => 'YOUR_CONSUMER_KEY',
         'consumer_secret' => 'YOUR_CONSUMER_SECRET',

         // Environment
         'environment' => 'sandbox', // on sandbox environment
         
         // Short code
         'short_code'  => 'SHORT_CODE', // This is your till or paybill

         // Identifier type of the shortcode
         'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_PAYBILL, // For paybills
         // 'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_TILL, // For till


         // Webhook URLS
         'confirmation_url' => 'https://domain.example/confirm.php',
         'validation_url'   => 'https://domain.example/validate.php',
      
      ]
);

$mpesa = new Mpesa($config);

// Register urls

try{

   $response = $mpesa->C2B()->registerURL(); // Returns the MpesaResponse class object

   echo $response;
   // or
   echo $response->getJSONString();

} catch(MpesaInternalException $e) {
   // This exception occurs when a configuration is missing e.g. consumer key
   echo $e->getMessage();

} catch(MpesaClientException $ce){
   // This occurs when the request has been sent to the mpesa servers but some invalid
   // data was supplied e.g. invalid consumer key
   
   echo $ce->getStatusCode(); // Returns http status code of the error
   echo $ce->getMessage(); // Returns the error message
   echo $ce->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($ce->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

} catch (MpesaServerException $se) {
   // This occurs when the request has been sent to the mpesa servers
   // but the server experienced some issues this is an error from the gateway and
   // is not the client fault

   echo $se->getStatusCode(); // Returns http status code of the error
   echo $se->getMessage(); // Returns the error message
   echo $se->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($se->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

}

模拟交易（C2B）

此操作用于在沙盒测试期间模拟交易，如果在生产环境中使用，将引发错误

use Hackdelta\Mpesa\Mpesa;
use Hackdelta\Mpesa\Main\MpesaConfig;
use Hackdelta\Mpesa\Extras\MpesaConstants;
use Hackdelta\Mpesa\Exceptions\MpesaInternalException;
use Hackdelta\Mpesa\Exceptions\MpesaClientExceptions;
use Hackdelta\Mpesa\Exceptions\MpesaServerException;

$config = new MpesaConfig(
      [
         // API Credentials
         'consumer_key'    => 'YOUR_CONSUMER_KEY',
         'consumer_secret' => 'YOUR_CONSUMER_SECRET',

         // Environment
         'environment' => 'sandbox', // on sandbox environment
         
         // Short code
         'short_code'  => 'SHORT_CODE', // This is your till or paybill

         // Identifier type of the shortcode
         'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_PAYBILL, // For paybills
         // 'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_TILL, // For til

      ]
);

$mpesa = new Mpesa($config);

// Simulate a transaction

try{

   $response = $mpesa->C2B()->simulate(
      '25470000000', // Phone number to simulate, use test credentials
      100, // Amount to transact
      'account number' // if simulating for paybill otherwise should be blank
   ); // Returns the MpesaResponse class object

   echo $response;
   // or
   echo $response->getJSONString();

} catch(MpesaInternalException $e) {
   // This exception occurs when a configuration is missing e.g. consumer key
   echo $e->getMessage();

} catch(MpesaClientException $ce){
   // This occurs when the request has been sent to the mpesa servers but some invalid
   // data was supplied e.g. invalid consumer key
   
   echo $ce->getStatusCode(); // Returns http status code of the error
   echo $ce->getMessage(); // Returns the error message
   echo $ce->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($ce->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

} catch (MpesaServerException $se) {
   // This occurs when the request has been sent to the mpesa servers
   // but the server experienced some issues this is an error from the gateway and
   // is not the client fault

   echo $se->getStatusCode(); // Returns http status code of the error
   echo $se->getMessage(); // Returns the error message
   echo $se->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($se->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

}

初始化STK推送（C2B）

此操作用于Lipa na Mpesa在线交易，需要以下配置

use Hackdelta\Mpesa\Mpesa;
use Hackdelta\Mpesa\Main\MpesaConfig;
use Hackdelta\Mpesa\Extras\MpesaConstants;
use Hackdelta\Mpesa\Exceptions\MpesaInternalException;
use Hackdelta\Mpesa\Exceptions\MpesaClientExceptions;
use Hackdelta\Mpesa\Exceptions\MpesaServerException;

$config = new MpesaConfig(
      [
         // API Credentials
         'consumer_key'    => 'YOUR_CONSUMER_KEY',
         'consumer_secret' => 'YOUR_CONSUMER_SECRET',

         // Environment
         'environment' => 'sandbox', // on sandbox environment
         
         // Short code
         'short_code'  => 'SHORT_CODE', // This is your till or paybill
         'business_short_code' => 'BUSINESS_SHORT_CODE', // This is your head office number which for
                                                         // paybills it's the same, leave this blank
                                                         // if you are using paybill

         // Identifier type of the shortcode
         'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_PAYBILL, // For paybills
         // 'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_TILL, // For til

         // Lipa na mpesa online passkey
         // For STK push
         'passkey' => 'PASSKEY',

         // STK callback URL
         'stk_callback_url' => 'https://domain.example/callback.php',

      ]
);

$mpesa = new Mpesa($config);

// Initiate an STK push request

try{

   $response = $mpesa->C2B()->initiateSTKPush(
      '25470000000', // Phone number to send request to
      100, // Amount to transact

      // Optional parameters
      'account number', // The account reference
      'description', // Description accompanying the transaction 
      'timestamp' // Your own timestamp

   ); // Returns the MpesaResponse class object

   echo $response;
   // or
   echo $response->getJSONString();

} catch(MpesaInternalException $e) {
   // This exception occurs when a configuration is missing e.g. consumer key
   echo $e->getMessage();

} catch(MpesaClientException $ce){
   // This occurs when the request has been sent to the mpesa servers but some invalid
   // data was supplied e.g. invalid consumer key
   
   echo $ce->getStatusCode(); // Returns http status code of the error
   echo $ce->getMessage(); // Returns the error message
   echo $ce->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($ce->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

} catch (MpesaServerException $se) {
   // This occurs when the request has been sent to the mpesa servers
   // but the server experienced some issues this is an error from the gateway and
   // is not the client fault

   echo $se->getStatusCode(); // Returns http status code of the error
   echo $se->getMessage(); // Returns the error message
   echo $se->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($se->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

}

检查STK推送查询状态（C2B）

此操作用于检查STK推送请求的状态

use Hackdelta\Mpesa\Mpesa;
use Hackdelta\Mpesa\Main\MpesaConfig;
use Hackdelta\Mpesa\Extras\MpesaConstants;
use Hackdelta\Mpesa\Exceptions\MpesaInternalException;
use Hackdelta\Mpesa\Exceptions\MpesaClientExceptions;
use Hackdelta\Mpesa\Exceptions\MpesaServerException;

$config = new MpesaConfig(
      [
         // API Credentials
         'consumer_key'    => 'YOUR_CONSUMER_KEY',
         'consumer_secret' => 'YOUR_CONSUMER_SECRET',

         // Environment
         'environment' => 'sandbox', // on sandbox environment
         
         // Short code
         'short_code'  => 'SHORT_CODE', // This is your till or paybill
         'business_short_code' => 'BUSINESS_SHORT_CODE', // This is your head office number which for
                                                         // paybills it's the same, leave this blank
                                                         // if you are using paybill

         // Identifier type of the shortcode
         'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_PAYBILL, // For paybills
         // 'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_TILL, // For til

         // Lipa na mpesa online passkey
         // For STK push
         'passkey' => 'PASSKEY',

      ]
);

$mpesa = new Mpesa($config);

// Check for STK request status

try{

   $response = $mpesa->C2B()->STKPushQuery('checkout request id'); // Returns the MpesaResponse class object

   echo $response;
   // or
   echo $response->getJSONString();

} catch(MpesaInternalException $e) {
   // This exception occurs when a configuration is missing e.g. consumer key
   echo $e->getMessage();

} catch(MpesaClientException $ce){
   // This occurs when the request has been sent to the mpesa servers but some invalid
   // data was supplied e.g. invalid consumer key
   
   echo $ce->getStatusCode(); // Returns http status code of the error
   echo $ce->getMessage(); // Returns the error message
   echo $ce->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($ce->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

} catch (MpesaServerException $se) {
   // This occurs when the request has been sent to the mpesa servers
   // but the server experienced some issues this is an error from the gateway and
   // is not the client fault

   echo $se->getStatusCode(); // Returns http status code of the error
   echo $se->getMessage(); // Returns the error message
   echo $se->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($se->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

}

发送金钱（B2B）

此操作用于从企业向企业发送金钱，需要以下配置

use Hackdelta\Mpesa\Mpesa;
use Hackdelta\Mpesa\Main\MpesaConfig;
use Hackdelta\Mpesa\Extras\MpesaConstants;
use Hackdelta\Mpesa\Exceptions\MpesaInternalException;
use Hackdelta\Mpesa\Exceptions\MpesaClientExceptions;
use Hackdelta\Mpesa\Exceptions\MpesaServerException;

$config = new MpesaConfig(
      [
         // API Credentials
         'consumer_key'    => 'YOUR_CONSUMER_KEY',
         'consumer_secret' => 'YOUR_CONSUMER_SECRET',

         // Environment
         'environment' => 'sandbox', // on sandbox environment
         
         // Short code
         'short_code'  => 'SHORT_CODE', // This is your till or paybill

         // Identifier type of the shortcode
         'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_PAYBILL, // For paybills
         // 'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_TILL, // For til

          // Query results URL
         'queue_timeout_url' => 'https://domain.example/callback.php',
         'result_url'        => 'https://domain.example/callback.php',

      ]
);

$mpesa = new Mpesa($config);

// Perform B2B transaction

try{

   $response = $mpesa->B2B()->send(
         50, // Amount
         'to', // The shortcode of the other organization
         'command id', // Check for appropriate command ids, some can be found in 
                        // the MpesaConstant class
         'receiver identifier type', // identifier of the reciever, expected   
                                    // MpesaConstants::MPESA_IDENTIFIER_TYPE_PAYBILL or
                                    // MpesaConstants::MPESA_IDENTIFIER_TYPE_TILL or
                                    // MpesaConstants::MPESA_IDENTIFIER_TYPE_SHORTCODE

         // Optional parameters
         'account reference', // The account number
         'remarks' // The remarks for the transactions
      ); // Returns the MpesaResponse class object

   echo $response;
   // or
   echo $response->getJSONString();

} catch(MpesaInternalException $e) {
   // This exception occurs when a configuration is missing e.g. consumer key
   echo $e->getMessage();

} catch(MpesaClientException $ce){
   // This occurs when the request has been sent to the mpesa servers but some invalid
   // data was supplied e.g. invalid consumer key
   
   echo $ce->getStatusCode(); // Returns http status code of the error
   echo $ce->getMessage(); // Returns the error message
   echo $ce->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($ce->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

} catch (MpesaServerException $se) {
   // This occurs when the request has been sent to the mpesa servers
   // but the server experienced some issues this is an error from the gateway and
   // is not the client fault

   echo $se->getStatusCode(); // Returns http status code of the error
   echo $se->getMessage(); // Returns the error message
   echo $se->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($se->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

}

发送金钱（B2C）

此操作用于从企业向客户发送金钱，例如工资支付，需要以下配置

use Hackdelta\Mpesa\Mpesa;
use Hackdelta\Mpesa\Main\MpesaConfig;
use Hackdelta\Mpesa\Extras\MpesaConstants;
use Hackdelta\Mpesa\Exceptions\MpesaInternalException;
use Hackdelta\Mpesa\Exceptions\MpesaClientExceptions;
use Hackdelta\Mpesa\Exceptions\MpesaServerException;

$config = new MpesaConfig(
      [
         // API Credentials
         'consumer_key'    => 'YOUR_CONSUMER_KEY',
         'consumer_secret' => 'YOUR_CONSUMER_SECRET',

         // Environment
         'environment' => 'sandbox', // on sandbox environment
         
         // Short code
         'short_code'  => 'SHORT_CODE', // This is your till or paybill

         // Identifier type of the shortcode
         'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_PAYBILL, // For paybills
         // 'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_TILL, // For til

          // Query results URL
         'queue_timeout_url' => 'https://domain.example/callback.php',
         'result_url'        => 'https://domain.example/callback.php',

      ]
);

$mpesa = new Mpesa($config);

// Perform B2C transaction

try{

   $response = $mpesa->B2C()->send(
         50, // Amount
         'to', // The shortcode of the other organization
         'command id', // Check for appropriate command ids, some can be found in 
                        // the MpesaConstant class

         // Optional parameters
         'remarks', // The remarks for the transactions
         'occasion' // Occasion for transaction
      ); // Returns the MpesaResponse class object

   echo $response;
   // or
   echo $response->getJSONString();

} catch(MpesaInternalException $e) {
   // This exception occurs when a configuration is missing e.g. consumer key
   echo $e->getMessage();

} catch(MpesaClientException $ce){
   // This occurs when the request has been sent to the mpesa servers but some invalid
   // data was supplied e.g. invalid consumer key
   
   echo $ce->getStatusCode(); // Returns http status code of the error
   echo $ce->getMessage(); // Returns the error message
   echo $ce->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($ce->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

} catch (MpesaServerException $se) {
   // This occurs when the request has been sent to the mpesa servers
   // but the server experienced some issues this is an error from the gateway and
   // is not the client fault

   echo $se->getStatusCode(); // Returns http status code of the error
   echo $se->getMessage(); // Returns the error message
   echo $se->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($se->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

}

检查交易状态（通用）

用于检查短代码的账户余额

use Hackdelta\Mpesa\Mpesa;
use Hackdelta\Mpesa\Main\MpesaConfig;
use Hackdelta\Mpesa\Extras\MpesaConstants;
use Hackdelta\Mpesa\Exceptions\MpesaInternalException;
use Hackdelta\Mpesa\Exceptions\MpesaClientExceptions;
use Hackdelta\Mpesa\Exceptions\MpesaServerException;

$config = new MpesaConfig(
      [
         // API Credentials
         'consumer_key'    => 'YOUR_CONSUMER_KEY',
         'consumer_secret' => 'YOUR_CONSUMER_SECRET',

         // Environment
         'environment' => 'sandbox', // on sandbox environment
         
         // Short code
         'short_code'  => 'SHORT_CODE', // This is your till or paybill

         // Identifier type of the shortcode
         'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_PAYBILL, // For paybills
         // 'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_TILL, // For til

         // User credential
         'initiator_name'     => 'YOUR_INITIATOR_NAME',
         'initiator_password' => 'YOUR_INITIATOR_PASSWORD',

          // Query results URL
         'queue_timeout_url' => 'https://domain.example/callback.php',
         'result_url'        => 'https://domain.example/callback.php',

      ]
);

$mpesa = new Mpesa($config);

// Check transaction status
try{

   $response = $mpesa->checkTransactionStatus(
         'transaction id', // The mpesa transaction id e.g. MXO1DGH5
         
         // Optional parameters
         'remarks', // The remarks for the transactions
         'occasion' // The occasion for the request
      ); // Returns the MpesaResponse class object

   echo $response;
   // or
   echo $response->getJSONString();

} catch(MpesaInternalException $e) {
   // This exception occurs hen a configuration is missing e.g. consumer key
   echo $e->getMessage();

} catch(MpesaClientException $ce){
   // This occurs when the request has been sent to the mpesa servers but some invalid
   // data was supplied e.g. invalid consumer key
   
   echo $ce->getStatusCode(); // Returns http status code of the error
   echo $ce->getMessage(); // Returns the error message
   echo $ce->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($ce->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

} catch (MpesaServerException $se) {
   // This occurs when the request has been sent to the mpesa servers
   // but the server experienced some issues this is an error from the gateway and
   // is not the client fault

   echo $se->getStatusCode(); // Returns http status code of the error
   echo $se->getMessage(); // Returns the error message
   echo $se->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($se->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

}

请求撤销（通用）

用于撤销交易

use Hackdelta\Mpesa\Mpesa;
use Hackdelta\Mpesa\Main\MpesaConfig;
use Hackdelta\Mpesa\Extras\MpesaConstants;
use Hackdelta\Mpesa\Exceptions\MpesaInternalException;
use Hackdelta\Mpesa\Exceptions\MpesaClientExceptions;
use Hackdelta\Mpesa\Exceptions\MpesaServerException;

$config = new MpesaConfig(
      [
         // API Credentials
         'consumer_key'    => 'YOUR_CONSUMER_KEY',
         'consumer_secret' => 'YOUR_CONSUMER_SECRET',

         // Environment
         'environment' => 'sandbox', // on sandbox environment
         
         // Short code
         'short_code'  => 'SHORT_CODE', // This is your till or paybill

         // Identifier type of the shortcode
         'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_PAYBILL, // For paybills
         // 'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_TILL, // For til

         // User credential
         'initiator_name'     => 'YOUR_INITIATOR_NAME',
         'initiator_password' => 'YOUR_INITIATOR_PASSWORD',

          // Query results URL
         'queue_timeout_url' => 'https://domain.example/callback.php',
         'result_url'        => 'https://domain.example/callback.php',

      ]
);

$mpesa = new Mpesa($config);

// Start a reversal
try{

   $response = $mpesa->reverseTransaction(
         'transaction id', // The mpesa transaction id to reverse e.g. MX1C1K2LIM
         10, // The amount to be reversed
         
         // Optional parameters
         'remarks', // The remarks for the transactions
         'occasion' // Occasion for the transaction
         
      ); // Returns the MpesaResponse class object

   echo $response;
   // or
   echo $response->getJSONString();

} catch(MpesaInternalException $e) {
   // This exception occurs when a configuration is missing e.g. consumer key
   echo $e->getMessage();

} catch(MpesaClientException $ce){
   // This occurs when the request has been sent to the mpesa servers but some invalid
   // data was supplied e.g. invalid consumer key
   
   echo $ce->getStatusCode(); // Returns http status code of the error
   echo $ce->getMessage(); // Returns the error message
   echo $ce->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($ce->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

} catch (MpesaServerException $se) {
   // This occurs when the request has been sent to the mpesa servers
   // but the server experienced some issues this is an error from the gateway and
   // is not the client fault

   echo $se->getStatusCode(); // Returns http status code of the error
   echo $se->getMessage(); // Returns the error message
   echo $se->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($se->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

}

检查余额（通用）

用于检查短代码的账户余额

use Hackdelta\Mpesa\Mpesa;
use Hackdelta\Mpesa\Main\MpesaConfig;
use Hackdelta\Mpesa\Extras\MpesaConstants;
use Hackdelta\Mpesa\Exceptions\MpesaInternalException;
use Hackdelta\Mpesa\Exceptions\MpesaClientExceptions;
use Hackdelta\Mpesa\Exceptions\MpesaServerException;

$config = new MpesaConfig(
      [
         // API Credentials
         'consumer_key'    => 'YOUR_CONSUMER_KEY',
         'consumer_secret' => 'YOUR_CONSUMER_SECRET',

         // Environment
         'environment' => 'sandbox', // on sandbox environment
         
         // Short code
         'short_code'  => 'SHORT_CODE', // This is your till or paybill

         // Identifier type of the shortcode
         'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_PAYBILL, // For paybills
         // 'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_TILL, // For til

         // User credential
         'initiator_name'     => 'YOUR_INITIATOR_NAME',
         'initiator_password' => 'YOUR_INITIATOR_PASSWORD',

          // Query results URL
         'queue_timeout_url' => 'https://domain.example/callback.php',
         'result_url'        => 'https://domain.example/callback.php',

      ]
);

$mpesa = new Mpesa($config);

// Check balance
try{

   $response = $mpesa->checkBalance(
         // Optional parameters
         'remarks', // The remarks for the transactions
         
      ); // Returns the MpesaResponse class object

   echo $response;
   // or
   echo $response->getJSONString();

} catch(MpesaInternalException $e) {
   // This exception occurs when a configuration is missing e.g. consumer key
   echo $e->getMessage();

} catch(MpesaClientException $ce){
   // This occurs when the request has been sent to the mpesa servers but some invalid
   // data was supplied e.g. invalid consumer key
   
   echo $ce->getStatusCode(); // Returns http status code of the error
   echo $ce->getMessage(); // Returns the error message
   echo $ce->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($ce->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

} catch (MpesaServerException $se) {
   // This occurs when the request has been sent to the mpesa servers
   // but the server experienced some issues this is an error from the gateway and
   // is not the client fault

   echo $se->getStatusCode(); // Returns http status code of the error
   echo $se->getMessage(); // Returns the error message
   echo $se->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($se->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

}

注册拉取请求回调URL（通用）

这是一个相对较新的API，建议您首先检查规范和Mpesa端点文档。此API用于从Safaricom请求交易报表，在此我们正在注册将接收拉取请求调用的结果的回调URL。

use Hackdelta\Mpesa\Mpesa;
use Hackdelta\Mpesa\Main\MpesaConfig;
use Hackdelta\Mpesa\Extras\MpesaConstants;
use Hackdelta\Mpesa\Exceptions\MpesaInternalException;
use Hackdelta\Mpesa\Exceptions\MpesaClientExceptions;
use Hackdelta\Mpesa\Exceptions\MpesaServerException;

$config = new MpesaConfig(
      [
         // API Credentials
         'consumer_key'    => 'YOUR_CONSUMER_KEY',
         'consumer_secret' => 'YOUR_CONSUMER_SECRET',

         // Environment
         'environment' => 'sandbox', // on sandbox environment
         
         // Short code
         'short_code'  => 'SHORT_CODE', // This is your till or paybill

         // Identifier type of the shortcode
         'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_PAYBILL, // For paybills
         // 'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_TILL, // For till

         // Pull request
         'organization_msisdn' => '0722000000', // Used for pull requests, this is the
                                                // number that receives confirmation messages
         'pull_callback_url'   => 'https://domain.example/callback.php'

      ]
);

$mpesa = new Mpesa($config);

// Register pull request callback URL
try{

   $response = $mpesa->pullRequestRegisterURL(); // Returns the MpesaResponse class object

   echo $response;
   // or
   echo $response->getJSONString();

} catch(MpesaInternalException $e) {
   // This exception occurs when a configuration is missing e.g. consumer key
   echo $e->getMessage();

} catch(MpesaClientException $ce){
   // This occurs when the request has been sent to the mpesa servers but some invalid
   // data was supplied e.g. invalid consumer key
   
   echo $ce->getStatusCode(); // Returns http status code of the error
   echo $ce->getMessage(); // Returns the error message
   echo $ce->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($ce->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

} catch (MpesaServerException $se) {
   // This occurs when the request has been sent to the mpesa servers
   // but the server experienced some issues this is an error from the gateway and
   // is not the client fault

   echo $se->getStatusCode(); // Returns http status code of the error
   echo $se->getMessage(); // Returns the error message
   echo $se->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($se->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

}

发送拉取请求（通用）

这是一个相对较新的API，建议您首先检查规范和Mpesa端点文档。此API用于从Safaricom请求交易报表

use Hackdelta\Mpesa\Mpesa;
use Hackdelta\Mpesa\Main\MpesaConfig;
use Hackdelta\Mpesa\Extras\MpesaConstants;
use Hackdelta\Mpesa\Exceptions\MpesaInternalException;
use Hackdelta\Mpesa\Exceptions\MpesaClientExceptions;
use Hackdelta\Mpesa\Exceptions\MpesaServerException;

$config = new MpesaConfig(
      [
         // API Credentials
         'consumer_key'    => 'YOUR_CONSUMER_KEY',
         'consumer_secret' => 'YOUR_CONSUMER_SECRET',

         // Environment
         'environment' => 'sandbox', // on sandbox environment
         
         // Short code
         'short_code'  => 'SHORT_CODE', // This is your till or paybill

         // Identifier type of the shortcode
         'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_PAYBILL, // For paybills
         // 'identifier_type' => MpesaConstants::MPESA_IDENTIFIER_TYPE_TILL, // For till

         // Pull request
         'organization_msisdn' => '0722000000', // Used for pull requests, this is the
                                                // number that receives confirmation messages
         'pull_callback_url'   => 'https://domain.example/callback.php'

      ]
);

$mpesa = new Mpesa($config);

// Initiate a pull request
try{

   $response = $mpesa->pullRequestQuery(
      '2019-07-31 20:35:21', // The start date in the format shown
      '2019-08-01 20:35:21', // The end date in the format shown
      0 // The offset
   ); // Returns the MpesaResponse class object

   echo $response;
   // or
   echo $response->getJSONString();

} catch(MpesaInternalException $e) {
   // This exception occurs when a configuration is missing e.g. consumer key
   echo $e->getMessage();

} catch(MpesaClientException $ce){
   // This occurs when the request has been sent to the mpesa servers but some invalid
   // data was supplied e.g. invalid consumer key
   
   echo $ce->getStatusCode(); // Returns http status code of the error
   echo $ce->getMessage(); // Returns the error message
   echo $ce->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($ce->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

} catch (MpesaServerException $se) {
   // This occurs when the request has been sent to the mpesa servers
   // but the server experienced some issues this is an error from the gateway and
   // is not the client fault

   echo $se->getStatusCode(); // Returns http status code of the error
   echo $se->getMessage(); // Returns the error message
   echo $se->getErrorBody(); //  Returns the json string of the error body returned from server
   print_r($se->getRequestParameters()); // An array of the request parameters sent i.e. the headers,
                                          // the request body, the URL hit, and method

}

高级用法

如果您对高级使用有任何疑问，请在问题选项卡中提出问题。示例可能包括

如果令牌存储在数据库中，则持久化令牌。
在不同类型的短代码之间切换，例如从普通C2B短代码切换到B2C短代码

这可以通过在发送下一个请求之前更改配置来实现。大多数这些都围绕配置文件本身，配置是通过引用传递的，因此一个更改会影响其余配置的更改。这是为了便于在不更改多个类的配置的情况下轻松操作配置。这种行为在类之间形成了一种共享数据；

TODO：添加高级使用的示例

如何贡献

在继续之前，请查看库规范以了解应遵循哪些方法和任何其他规范。

Git是我们首选的版本控制系统，GitHub是我们当前的代码库平台。以下是我们的Git工作方式：

通常我们更倾向于分支而不是分叉，以简化内部协作。
如有疑问，请使用功能分支和gitflow作为您的分支命名方案。
我们已经决定采用Git功能分支工作流程。
保持您的代码库干净；删除已合并的分支并避免提交特定于您的开发环境的文件（例如 .DS_Store）。
请遵循有关良好提交消息的指导。
考虑使用GPG密钥签名提交。
功能分支具有以下前缀：feature/。
在将代码推送到master并部署到生产之前，请先获得项目负责人的批准。

获取帮助

如果您在项目中遇到任何问题，可以在项目的问题板上升级问题。

安全

如果您发现任何安全相关的问题，请通过电子邮件bngetich69@gmail.com而不是使用问题跟踪器。

测试

TODO

hackdelta / mpesa

维护者

详细信息