README

一个为 Laravel 开发者提供的简单包，用于消费 Laravel 8 的 Kopokopo API。

安装

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

composer require sparkworldke/kopokopo-laravel-support

配置

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

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。

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

  // 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，因此在使用 Kopo Kopo API 之前，Kopokopo API 需要使用应用程序的 access token 代表应用程序调用 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 来接收支付通知，这些支付通知是您在 Kopo kopo 应用中发生的支付和交易。要注册 URL，请确保在 config/kopokopo.php 中所有 webhooks 下的 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 webhooks 配置中指定的所有 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 Push）

您可以通过 STK Push 接收 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
);

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 位置标头将包含新创建的 incoming payment 的 URL。

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

查询 incoming payment 状态

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

创建支付接收者

您可以为将来支付的目的添加外部接收者，就像创建联系人一样。以下是可以创建的不同类型的 pay recipients 示例。

(a). 移动钱包

创建移动钱包接收者的 pay recipient；

$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 位置标头中返回。

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

(b). 银行账户

(c). 外部收银台

(c). Paybill

发起 outgoing payment

查询出账支付状态

转账到您的结算账户

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

轮询

在指定日期之间轮询特定收银机或整个公司的Buygoods交易。

交易短信通知API请求

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

变更日志

请参阅变更日志了解最近的变化详情。

测试

$ composer test

贡献

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

安全漏洞

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

许可证

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

sparkworldke/kopokopo-laravel-support

维护者

详细信息