README

一个简单的包，为 Laravel 开发者提供使用 Laravel 8 的 Kopokopo API 的能力。

安装

您可以使用 composer 和安装命令轻松安装此包：

composer require patrickmwangi017/laravel-kopokopo

配置

安装包后，运行以下命令以发布配置：

php artisan kopokopo:install

这将帮助发布 config/kopokopo.php 文件。此 kopokopo 配置 文件是您添加所有 Kopokopo API 配置的地方。这包括应用程序运行的环境（沙箱或生产）、回调 URL 和所需凭证。

<?php

return [
    // Set this to false if you cannot authenticate due to SSL certificate problem.
    'curl_ssl_verify' => false,

    // When you are testing in sandbox environment this remains true, to go to a live environment set it to false
    'sandbox' => false,

    /* The below values should not be hardcoded for security reason. Add these variables in .env
    *  i.e KOPOKOPO_CLIENT_ID, KOPOKOPO_CLIENT_SECRET, KOPOKOPO_API_KEY
    */
    # This is the application id acquired after you create an Authorization application on the kopokopo dashboard
    'client_id' => env('KOPOKOPO_CLIENT_ID', 'EXAMPLE_CLIENT_ID'),

    # The kopokopo application client secret
    'client_secret' => env('KOPOKOPO_CLIENT_SECRET', 'EXAMPLE_CLIENT_SECRET'),

    # The kopokopo application api key
    'api_key' => env('KOPOKOPO_API_KEY', 'EXAMPLE_APIKEY'),

    // Define the scope of your applications control on kopokopo transaction. Using company will control transactions for all till numbers regardless
    'scope' => 'till', //i.e company, till

    // The business till number given to you by Kopokopo
    'till_number' => '0000000',

    // The business till number given to you by Kopokopo
    'stk_till_number' => 'K000000',

    // Preferred transacting currency i.e KES, USD, AUD
    'currency' => 'KES',

    // Webhooks are a means of getting notified on your laravel application of events in the Kopokopo application. i.e https://api-docs.kopokopo.com/#webhooks
    // Below values will be used to register your webhooks on Kopokopo. For it to work, update the values and use Kopokopo::subscribeRegisteredWebhooks() to register
    'webhooks' => [
        'buygoods_transaction_received' => 'https://example.com/k2transrec',
        'buygoods_transaction_reversed' => 'https://example.com/k2transrev',
        'b2b_transaction_received' => 'https://example.com/k2b2btransrec',
        'm2m_transaction_received' => 'https://example.com/k2m2mtransrec',
        'settlement_transfer_completed' => 'https://example.com/k2settcomp',
        'customer_created' => 'https://example.com/k2custcr'
    ],

    // This webhook is used to get notified of a successful Mpesa stk payment
    'stk_payment_received_webhook' => 'https://example.com/mobile-stk-received',

];

对于生产环境，您需要替换为生产凭证，并将 'sandbox' => false。

出于安全原因，您可能希望将 API 凭证定义在 env 文件中。例如：

  // config/kopokopo.php
  ...
  'client_id' => env('KOPOKOPO_CLIENT_ID'),
  'client_secret'   => env('KOPOKOPO_CLIENT_SECRET'),
  'api_key' => env('KOPOKOPO_API_KEY'),
  ...

# .env
# ...
KOPOKOPO_CLIENT_ID="BOPgOFAKE0gsUNH794EfjtmLiKTJ1BfMXjTZ2FrZM8"
KOPOKOPO_CLIENT_SECRET="8KGfakeHzHezjLpHzyP3NdJFd-T-Q1DewYyKrpiBX_s"
KOPOKOPO_API_KEY="EuavW1N-FAKEk4D-9XRLPudGGZ3yFBiygEwfkWDes_I"
# ...

使用方法

首先...授权

Kopo Kopo 使用 OAuth2 允许访问 Kopo Kopo API，因此在进行任何操作之前，Kopokopo API 预期应用程序 访问令牌 被用于代表应用程序调用 Kopo Kopo API。要获取令牌，您需要调用令牌服务，如下所示：

<?php
use Kopokopo;
...
// Get the token
$token=Kopokopo::getToken();

//introspect token
Kopokopo::introspectToken($token);

//revoke access token
Kopokopo::revokeToken($token);

Webhook 订阅

此 API 允许您通过注册回调 URL 来接收支付通知，这些 URL 用于接收在您的 Kopo kopo 应用中发生的支付和交易。要注册 URL，请确保 config/kopokopo.php 中的所有 webhook URL 都填写了有效的 URL。查看 https://developers.kopokopo.com/guides/webhooks 了解每个 webhook 的功能。
在沙箱上进行测试时，您可以使用 ngrok 将您的回调暴露给互联网。然后在 Kopokopo 门面上调用的 registerWebhooks()。例如：

通过终端命令进行 Webhook 订阅

在您的终端中运行以下命令来发布任何 webhook：

php artisan kopokopo:subscribe

示例

$ php artisan kopokopo:subscribe

  Enter Event Type:
  > stk_payment_received_webhook
  Callback URL i.e https://example.com/b2c-callback:
  > https://example.com/api//b2c-callback
  Scope: i.e till,business [till]:
  > till
  STK Enabled Till Number [K000000]:
  > K000000

您可以使用 --all 选项来订阅在 kopokopo webhook 配置中指定的所有 webhook，例如：

php artisan kopokopo:subscribe --all

或者

...
$token=Kopokopo::getToken();

// subscribe all webhooks registered in config file
$response = Kopokopo::authenticate($token)->subscribeRegisteredWebhooks();
 
 //subscribe a specific webhook
 $res = Kopokopo::authenticate($token)->subscribeWebhook(
    event_type: 'buygoods_transaction_received',
    url: 'https://myawesomeapplication.com/destination',
    scope: 'till',
    till: 7777777,
 )
 
// HTTP/1.1 201 Created Location: https://sandbox.kopokopo.com/api/v1/webhook_subscriptions/d76265cd-0951-e522-80da-0aa34a9b2388
...

在成功创建 webhook 订阅后，API 将返回 true，否则您将收到精确的错误作为 JSON HTTP 响应；

发起 Mpesa 支付（STK 推送）

您可以通过 STK 推送接收 M-PESA 用户的支付。您可以像这样发起支付：

$res= Kopokopo::authenticate('my_access_token')->stkPush(
    amount:  2230,
    phone: '+254799999999',
    first_name: 'Michael',//optional
    last_name: 'Gatuma',//optional
    email: 'clientemail@gmail.com',//optional
    metadata: [
        'user_id'=>1,
        'action'=>'deposit'
    ],//optional
    stk_till_number: 'STK_TILL_NUMBER'
);

if($res['status'] == 'success')
{
    dump ("The resource location is:" . json_encode($res['location']));
    // => 'https://sandbox.kopokopo.com/api/v1/incoming_payments/247b1bd8-f5a0-4b71-a898-f62f67b8ae1c'
}

在成功请求后，将返回 HTTP 状态 201，并且 HTTP 头中的 location 将包含新创建的传入支付的 URL。

HTTP/1.1 201 Created Location: https://sandbox.kopokopo.com/api/v1/incoming_payments/247b1bd8-f5a0-4b71-a898-f62f67b8ae1c

查询传入支付状态

$res=Kopokopo::getStatus($location);

创建支付接收者

您可以为将来支付的目的地添加外部接收者，类似于创建联系人。以下是可以创建的不同类型的支付接收者及其示例。

(a) 移动钱包

为移动钱包接收者创建支付接收者；

$res=Kopokopo::addPaymentRecipient(
$access_token,$first_name,$last_name,$email,$phone
);
$create_recipient_response = Kopokopo::PayService()->addPayRecipient([
  'type' => 'mobile_wallet',
  'firstName'=> 'Michael',
  'lastName'=> 'Gatuma',
  'email'=> 'example@nomail.net',
  'phoneNumber'=> '+254999999999',
  'network'=> 'Safaricom',
  'accessToken' => 'myRand0mAcc3ssT0k3n'
]);

if($create_recipient_response['status'] == 'success')
{
    echo "The resource location is:" . json_encode($create_recipient_response['location']);
}

在成功创建PAY收款人后，将返回HTTP响应代码201。收款人资源的URL也将在HTTP Location Header中返回。

HTTP/1.1 201 Created Location: https://sandbox.kopokopo.com/api/v1/pay_recipients/c7f300c0-f1ef-4151-9bbe-005005aa3747

(b). 银行账户

(c). 外部收银台

(c). Paybill

发起出款

查询出款状态

转账到您的结算账户

将资金转账到您的预批准结算账户（银行账户或移动钱包）。

轮询

在指定日期范围内轮询特定收银台或整个公司的Buygoods交易。

交易短信通知API请求

在收到客户的付款后，向您的客户发送短信通知。

变更日志

请参阅变更日志以获取有关最近更改的更多信息。

测试

$ composer test

贡献

感谢您考虑为laravel-kopokopo做出贡献。欢迎提交拉取请求和问题。在继续之前，请确保检查开放的问题和PR。查看contributing.md以查看待办事项列表。

安全漏洞

如果您在laravel-kopokopo中发现安全漏洞，请通过mgates4410@gmail.com将电子邮件发送给Michael Gatuma。所有安全漏洞都将得到及时解决。

许可证

laravel-kopokopo软件包是开源软件，受MIT许可证许可。

patrickmwangi017 / laravel-kopokopo

维护者

详细信息