README

一个简单的包，供Laravel开发者使用，以便消费laravel 8的Kopokopo API。

安装

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

composer require michaelgatuma/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。

出于安全原因，您可能想在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，因此在进行任何操作之前，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，您将通过这些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，并且location HTTP头将包含新创建的传入支付的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 交易。

交易 SMS 通知 API 请求

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

变更日志

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

测试

$ composer test

贡献

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

安全漏洞

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

许可证

laravel-kopokopo 软件包是开源软件，许可协议为 MIT 许可证

michaelgatuma / laravel-kopokopo

维护者

详细信息