README

这是一个为 Safaricom 的 M-Pesa API 设计的 PHP 包。该 API 允许商家发起 C2B 在线结账（通过网页支付账单）交易。商家提交认证详情、交易详情、回调 URL 和回调方法。

提交请求后，商家会立即收到请求有效性的反馈。C2B API 通过 USSD 推送处理客户验证和认证。然后客户确认交易。如果客户验证失败或客户拒绝交易，API 将回调给商家。否则，交易将被处理，并通过回调通知其状态。

如果您喜欢使用此包，请花一点时间 买我一些咖啡。

安装

通过 Composer 拉取包。

原生插件

当使用纯 PHP 时，修改您的 composer.json 文件以包含

  "scripts": {
    "post-update-cmd": [
        "SmoDav\\Mpesa\\Support\\Installer::install"
    ]
  },

此脚本将默认配置文件复制到项目根目录下的配置文件夹中。现在继续要求包。

常规安装

运行 composer require smodav/mpesa 以获取包的最新稳定版本。

从先前版本迁移

包的 v5 版本更改了实现并引入了一些破坏性更改。请参阅 CHANGELOG。

此包的 v4 版本使用新的配置设置。您需要更新您的配置文件才能将 v3 升级到 v4。v2 仍然不兼容，因为它使用较旧的 API 版本。

Laravel

当使用 Laravel 5.5+ 时，包将自动注册。对于 laravel 5.4 及以下版本，在您的 config/app.php 中包含服务提供者和其别名。

'providers' => [
    SmoDav\Mpesa\Laravel\ServiceProvider::class,
],

'aliases' => [
    'STK'       => SmoDav\Mpesa\Laravel\Facades\STK::class,
    'Simulate'  => SmoDav\Mpesa\Laravel\Facades\Simulate::class,
    'Registrar' => SmoDav\Mpesa\Laravel\Facades\Registrar::class,
    'Identity'  => SmoDav\Mpesa\Laravel\Facades\Identity::class,
],

使用以下方式发布包特定配置

php artisan vendor:publish

其他框架

要实现此包，需要一个配置仓库，因此任何其他框架都需要创建其自己的 ConfigurationStore 和 CacheStore 接口的实现。

配置

该包允许您拥有多个账户。每个账户都将拥有其特定的凭证和端点，这些凭证和端点与其他账户独立。您需要设置默认账户，用于所有交易，您可以在每个请求中覆盖它。该包提供了两个默认账户，您可以对其进行修改。

/*
|--------------------------------------------------------------------------
| Default Account
|--------------------------------------------------------------------------
|
| This is the default account to be used when none is specified.
*/

'default' => 'staging',

/*
|--------------------------------------------------------------------------
| File Cache Location
|--------------------------------------------------------------------------
|
| When using the Native Cache driver, this will be the relative directory
| where the cache information will be stored.
*/

'cache_location' => '../cache',

/*
|--------------------------------------------------------------------------
| Accounts
|--------------------------------------------------------------------------
|
| These are the accounts that can be used with the package. You can configure
| as many as needed. Two have been setup for you.
|
| Sandbox: Determines whether to use the sandbox, Possible values: sandbox | production
| Initiator: This is the username used to authenticate the transaction request
| LNMO:
|    shortcode: The till number
|    passkey: The passkey for the till number
|    callback: Endpoint that will be be queried on completion or failure of the transaction.
|
*/

'accounts' => [
    'staging' => [
        'sandbox' => true,
        'key' => 'your development consumer key',
        'secret' => 'your development consumer secret',
        'initiator' => 'your development username',
        'id_validation_callback' => 'http://example.com/callback?secret=some_secret_hash_key',
        'lnmo' => [
            'paybill' => 'your development paybill number',
            'shortcode' => 'your development business code',
            'passkey' => 'your development passkey',
            'callback' => 'http://example.com/callback?secret=some_secret_hash_key',
        ]
    ],

    'paybill_1' => [
        'sandbox' => false,
        'key' => 'your production consumer key',
        'secret' => 'your production consumer secret',
        'initiator' => 'your production username',
        'id_validation_callback' => 'http://example.com/callback?secret=some_secret_hash_key',
        'lnmo' => [
            'paybill' => 'your production paybill number',
            'shortcode' => 'your production business code',
            'passkey' => 'your production passkey',
            'callback' => 'http://example.com/callback?secret=some_secret_hash_key',
        ]
    ],

    'paybill_2' => [
        'sandbox' => false,
        'key' => 'your production consumer key',
        'secret' => 'your production consumer secret',
        'initiator' => 'your production username',
        'id_validation_callback' => 'http://example.com/callback?secret=some_secret_hash_key',
        'lnmo' => [
            'paybill' => 'your production paybill number',
            'shortcode' => 'your production business code',
            'passkey' => 'your production passkey',
            'callback' => 'http://example.com/callback?secret=some_secret_hash_key',
        ]
    ],
],

您可以根据需要添加多个账户，并使用 STK、Register 和 Simulate 上的 usingAccount 方法切换连接，如下所示。

此外，请注意配置中 business 短码 和您的 paybill 号码 之间的区别，因为弄错它们将花费您大量的时间进行调试。

用法

对于纯 PHP，您需要在任何请求之前初始化核心引擎，如下所示。该包包含纯 PHP 的缓存和配置存储实现，NativeCache 和 NativeConfig。

NativeConfig 接收配置文件的自定义位置作为第一个构造函数参数。如果创建实例时未传递值，则将使用默认配置，并在项目的 configs 目录下查找根目录中的配置文件。

NativeCache 接收自定义目录路径作为第一个构造函数参数。该路径表示缓存应存储文件的位置。如果没有提供路径，则将使用配置中的默认缓存位置。

use GuzzleHttp\Client;
use SmoDav\Mpesa\Engine\Core;
use SmoDav\Mpesa\Native\NativeCache;
use SmoDav\Mpesa\Native\NativeConfig;

require "vendor/autoload.php";

$config = new NativeConfig();
$cache = new NativeCache($config->get('cache_location'));
// or
$cache = new NativeCache(__DIR__ . '/../some/awesome/directory');

$core = new Core(new Client, $config, $cache);

URL 注册

提交（shortCode = null，confirmationURL = null，validationURL = null，onTimeout = 'Completed|Cancelled'，account = null）

注册回调URL

Vanilla

use SmoDav\Mpesa\C2B\Registrar;

$conf = 'http://example.com/mpesa/confirm?secret=some_secret_hash_key';
$val = 'http://example.com/mpesa/validate?secret=some_secret_hash_key';


$response = (new Registrar($core))->register(600000)
    ->onConfirmation($conf)
    ->onValidation($val)
    ->submit();

/****** OR ********/
$response = (new Registrar($core))->submit(600000, $conf, $val);

当有多个账户时，请使用 usingAccount 方法进行切换。我们目前有 staging、paybill_1 和 paybill_2，其中 staging 是默认值。

$response = (new Registrar($core))
    ->register(600000)
    ->usingAccount('paybill_1')
    ->onConfirmation($conf)
    ->onValidation($val)
    ->submit();

/****** OR ********/
$response = (new Registrar($core))->submit(600000, $conf, $val, null, 'paybill_1');

Laravel

use SmoDav\Mpesa\Laravel\Facades\Registrar;

$conf = 'http://example.com/mpesa/confirm?secret=some_secret_hash_key';
$val = 'http://example.com/mpesa/validate?secret=some_secret_hash_key';

$response = Registrar::register(600000)
    ->onConfirmation($conf)
    ->onValidation($val)
    ->submit();

/****** OR ********/
$response = Registrar::submit(600000, $conf, $val);

使用 paybill_1 账户

use SmoDav\Mpesa\Laravel\Facades\Registrar;

$response = Registrar::register(600000)
    ->usingAccount('paybill_1')
    ->onConfirmation($conf)
    ->onValidation($val)
    ->submit();

/****** OR ********/
$response = Registrar::submit(600000, $conf, $val, null, 'paybill_1');

模拟交易

push(amount = null，number = null，reference = null，account = null，command = null)

启动C2B模拟交易请求。

注意，在启动C2B模拟时，设置命令类型是可选的，默认将使用 CustomerPaybillOnline。

Vanilla

use SmoDav\Mpesa\C2B\Simulate;

$simulate = new Simulate($core)

$response = $simulate->request(10)
    ->from(254722000000)
    ->usingReference('Some Reference')
    ->push();

/****** OR ********/
$response = $simulate->push(10, 254722000000, 'Some Reference');

使用 paybill_1 账户

$response = $simulate->request(10)
    ->from(254722000000)
    ->usingReference('Some Reference')
    ->usingAccount('paybill_1')
    ->push();

/****** OR ********/
$response = $simulate->push(10, 254722000000, 'Some Reference', 'paybill_1');

使用 CustomerBuyGoodsOnline 命令

$response = $simulate->request(10)
    ->from(254722000000)
    ->usingReference('Some Reference')
    ->setCommand(CUSTOMER_BUYGOODS_ONLINE)
    ->push();

/****** OR ********/
$response = $simulate->push(10, 254722000000, 'Some Reference', null, CUSTOMER_BUYGOODS_ONLINE);

Laravel

use SmoDav\Mpesa\Laravel\Facades\Simulate;

$response = Simulate::request(10)
    ->from(254722000000)
    ->usingReference('Some Reference')
    ->push();

/****** OR ********/
$response = Simulate::push(10, 254722000000, 'Some Reference');

使用 paybill_1 账户

use SmoDav\Mpesa\Laravel\Facades\Simulate;

$response = Simulate::request(10)
    ->from(254722000000)
    ->usingReference('Some Reference')
    ->usingAccount('paybill_1')
    ->push();

/****** OR ********/
$response = Simulate::push(10, 254722000000, 'Some Reference', 'paybill_1');

使用 CustomerBuyGoodsOnline 命令

use SmoDav\Mpesa\Laravel\Facades\Simulate;

$response = Simulate::request(10)
    ->from(254722000000)
    ->usingReference('Some Reference')
    ->setCommand(CUSTOMER_BUYGOODS_ONLINE) 
    ->push();

/****** OR ********/
$response = Simulate::push(10, 254722000000, 'Some Reference', null, CUSTOMER_BUYGOODS_ONLINE);

STK PUSH

push(amount = null，number = null，reference = null，description = null，account = null，command = null)

启动C2B STK Push请求。

注意，在启动STK Push时，设置命令类型是可选的，默认将使用 CustomerPaybillOnline。

Vanilla

use SmoDav\Mpesa\C2B\STK;

$stk = new STK($core);

$response = $stk->request(10)
    ->from(254722000000)
    ->usingReference('Some Reference', 'Test Payment')
    ->push();

/****** OR ********/
$response = $stk->push(10, 254722000000, 'Some Reference', 'Test Payment');

使用 paybill_2 账户

$response = $stk->request(10)
    ->from(254722000000)
    ->usingAccount('paybill_2')
    ->usingReference('Some Reference', 'Test Payment')
    ->push();

/****** OR ********/
$response = $stk->push(10, 254722000000, 'Some Reference', 'Test Payment', 'paybill_2');

使用 CustomerBuyGoodsOnline 命令

$response = $stk->request(10)
    ->from(254722000000)
    ->usingReference('Some Reference', 'Test Payment')
    ->setCommand(CUSTOMER_BUYGOODS_ONLINE)
    ->push();

/****** OR ********/
$response = $stk->push(10, 254722000000, 'Some Reference', 'Test Payment', null, CUSTOMER_BUYGOODS_ONLINE);

Laravel

use SmoDav\Mpesa\Laravel\Facades\STK;

$response = STK::request(10)
    ->from(254722000000)
    ->usingReference('Some Reference', 'Test Payment')
    ->push();

/****** OR ********/
$response = STK::push(10, 254722000000, 'Some Reference', 'Test Payment');

使用 paybill_2 账户

use SmoDav\Mpesa\Laravel\Facades\STK;

$response = STK::request(10)
    ->from(254722000000)
    ->usingAccount('paybill_2')
    ->usingReference('Some Reference', 'Test Payment')
    ->push();

$response = STK::push(10, 254722000000, 'Some Reference', 'Test Payment', 'paybill_2');

使用 CustomerGoodsOnline 命令

use SmoDav\Mpesa\Laravel\Facades\STK;

$response = STK::request(10)
    ->from(254722000000)
    ->usingReference('Some Reference', 'Test Payment')
    ->setCommand(CUSTOMER_BUYGOODS_ONLINE) 
    ->push();

$response = STK::push(10, 254722000000, 'Some Reference', 'Test Payment', null, CUSTOMER_BUYGOODS_ONLINE);

STK PUSH交易验证

validate(merchantReferenceId，account = null)

验证C2B STK Push交易。

Vanilla

use SmoDav\Mpesa\C2B\STK;

$stk = new STK($core);
    
$response = $stk->validate('ws_CO_16022018125');

使用 paybill_2 账户

$response = $stk->validate('ws_CO_16022018125', 'paybill_2');

Laravel

use SmoDav\Mpesa\Laravel\Facades\STK;

$response = STK::validate('ws_CO_16022018125');

使用 paybill_1 账户

use SmoDav\Mpesa\Laravel\Facades\STK;

$response = STK::validate('ws_CO_16022018125', 'paybill_2');

上线时，您应将配置文件中的 default 值更改为生产账户。

许可证

M-Pesa包是开源软件，使用MIT许可证授权。