README

这是一个辅助PHP开发者使用Kopokopo API的模块

安装

您可以通过composer安装PHP SDK。

建议使用Composer安装SDK。

composer require sparkworld/kopokopoke-laravel

初始化

该软件包应该配置您的客户端ID和客户端密钥，您可以从kopokopo应用程序的账户中获取。

//Store your client id and client secret as environment variables

//Including the kopokopo sdk
use Kopokopo\SDK\K2;

// do not hard code these values
$options = [
    'clientId' => 'YOUR_CLIENT_ID', 
    'clientSecret' => 'YOUR_CLIENT_SECRET',
    'apiKey' => 'YOUR_API_KEY',
    'baseUrl' => 'https://sandbox.kopokopo.com'
];

$K2 = new K2($options);

初始化后，您可以按以下方式获取提供的服务实例

令牌 : $tokens = $K2->TokenService();
Webhooks : $webhooks = $K2->Webhooks();
STK PUSH : $stk = $K2->StkService();
支付 : $pay = $K2->PayService();
结算转账 : $transfer = $K2->SettlementTransferService();
PollingService : $polling = $K2->PollingService();
SmsNotificationService : $sms_notification = $K2->SmsNotificationService();

使用方法

令牌

在向Kopokopo API发送数据时，您需要传递访问令牌。

这将返回accessToken和expiresIn值

use Kopokopo\SDK\K2;

// Do not hard code these values
$options = [
  'clientId' => 'YOUR_CLIENT_ID', 
  'clientSecret' => 'YOUR_CLIENT_SECRET',
  'apiKey' => 'YOUR_API_KEY',
  'baseUrl' => 'https://sandbox.kopokopo.com'
];

$K2 = new K2($options);

// Get one of the services
$tokens = $K2->TokenService();

// Use the service
$result = $tokens->getToken();

//print the result
print_r($result);

Webhooks

消费

// TODO: review this
$router->map('POST', '/webhook', function () {
    global $K2;
    global $response;

    $webhooks = $K2->Webhooks();

    $json_str = file_get_contents('php://input');
    var_dump($json_str);

    $response = $webhooks->webhookHandler($json_str, $_SERVER['HTTP_X_KOPOKOPO_SIGNATURE']);

    echo json_encode($response);
});

$webhooks = $K2->Webhooks();

//To subscribe to a webhook
$response = $webhooks->subscribe([
    'eventType' => 'buygoods_transaction_received',
    'url' => 'https://:8000/webhook',
    'scope' => 'till',
    'scopeReference' => '000000',
    'accessToken' => 'my_access_token'
]);

print_r($response);

STK PUSH

$stk = $K2->StkService();
$result = $stk->initiateIncomingPayment([
                'paymentChannel' => 'M-PESA STK Push',
                'tillNumber' => 'K000000',
                'firstName' => 'Jane',
                'lastName' => 'Doe',
                'phoneNumber' => '0712345678',
                'amount' => 3455,
                'email' => 'example@example.com',
                'callbackUrl' => 'https://:8000/test',
                'accessToken' => 'myRand0mAcc3ssT0k3n',
            ]);
print_r($result);

有关其他使用示例，请查看示例应用程序。

服务

目前唯一支持的ISO货币代码是：KES

`TokenService`

使用$TokenService->getToken()获取访问令牌。

响应将具有以下结构

[ 'status' => 'success',
  'data' => [
    'accessToken' => 'GT6576QGYdYh8i5s8DnxUQVphFewh-8eiO2',
    'tokenType' => 'Bearer',
    'expiresIn' => 3600,
    'createdAt' => '2021-04-06T13:49:50+03:00'
  ]
]

注意：访问令牌是发送后续请求所必需的

使用$TokenService->revokeToken(['accessToken' => 'myRand0mAcc3ssT0k3n'])来吊销访问令牌。

注意：访问令牌不能用于发送后续请求

使用$TokenService->introspectToken(['accessToken' => 'myRand0mAcc3ssT0k3n'])来检查令牌。
使用$TokenService->infoToken(['accessToken' => 'myRand0mAcc3ssT0k3n'])来获取有关令牌的更多信息

`StkService`

$StkService->initiateIncomingPayment([ stkOptions ])： stkOptions：包含以下键的数组数组
- tillNumber：您从Kopo Kopo仪表板获得的在线支付短码 必需
- firstName：客户的姓氏
- lastName：客户的姓氏
- phoneNumber：从该手机号码拉取资金。 必需
- email：客户的电子邮件地址
- currency：3位ISO格式货币代码。 必需
- amount：要收取的金额。 必需
- callbackUrl：结果将被提交到的URL 必需
- paymentChannel：支付渠道。默认值为："M-PESA STK Push"。 必需
- accessToken：从TokenService响应中获取 必需
- metadata：它是一个包含最多5个键值对的哈希表
$StkService->getStatus([location ]):
- location：您发送请求时获得的请求位置
- accessToken：从TokenService响应中获取 必需

`PayService`

PayService->addPayRecipient([ payRecipientOptions ])：payRecipientOptions：包含以下键的数组数组
- type：收款人类型 必需
  - 移动钱包收款人（mobile_wallet）
    - firstName：收款人的名字 必需
    - lastName：收款人的姓氏 必需
    - phoneNumber：收款人的电话号码 必需
    - email：收款人的电子邮件地址
    - network：收款人的网络 必需
  - 银行账户收款人（bank_account）
    - accountName：收款人的账户名称 必需
    - accountNumber：收款人的账户号码 必需
    - bankBranchRef：从kopokopo仪表板获取的银行分支参考 必需
    - settlementMethod：结算方式 必需
  - 外部收银台收款人（till）
    - tillNumber：收款人的收银台号码 必需
    - tillName：收款人的收银台名称 必需
  - Paybill（paybill）
    - paybillName：收款人的Paybill名称 必需
    - paybillNumber：收款人的Paybill号码 必需
    - paybillAccountNumber：收款人的账户号码 必需
- accessToken：从TokenService响应中获取 必需
PayService->sendPay([ payOptions ])：payOptions：包含以下键的数组数组
- destinationType：收款人类型 必需
- destinationReference：收款人参考 必需
- currency：3位ISO格式货币代码。 必需
- amount：要收取的金额。 必需
- callbackUrl：结果将被提交到的URL 必需
- description：支付描述 必需
- tags：与支付相关的标签
- category：支付所属的类别
- accessToken：从TokenService响应中获取 必需
- metadata：它是一个包含最多5个键值对的哈希表
PayService->getStatus([ location ]):
- location：您发送请求时获得的请求位置
- accessToken：从TokenService响应中获取 必需

有关更多信息，请参阅https://api-docs.kopokopo.com/#send-money-pay

`SettlementTransferService`

SettlementTransferService->createMerchantBankAccount([ accountOpts ])：accountOpts：包含以下键的数组数组
- accountName：结算账户名称 必需
- bankBranchRef：结算银行分支参考 必需
- accountNumber：结算账户号码 必需
- settlementMethod：结算方式 必需
- accessToken：从TokenService响应中获取 必需
SettlementTransferService->createMerchantWallet([ accountOpts ])：accountOpts：包含以下键的数组数组
- phoneNumber：结算的电话号码 必需
- network：结算的移动货币网络 必需
- accessToken：从TokenService响应中获取 必需
SettlementTransferService->settleFunds([ settleOpts ])：settleOpts：包含以下键的数组数组
- destinationType：目的地类型 针对目标转账必需
- destinationReference：目的地参考 针对目标转账必需
- currency：3位ISO格式货币代码。 针对目标转账必需
- amount：结算金额。 针对目标转账必需 备注：如果不包含，则将结算全部余额。
- accessToken：从TokenService响应中获取 必需
SettlementTransferService->getStatus([ location ]):
- location：您发送请求时获得的请求位置
- accessToken：从TokenService响应中获取 必需

有关更多信息，请参阅api-docs#transfer

`PollingService`

PollingService->pollTransactions([ pollingOpts ])：pollingOpts：包含以下键的数组数组
- fromTime：轮询请求的起始时间
- toTime：轮询请求的结束时间
- scope：轮询请求的范围
- scopeReference：作用域引用 对于 'Till' 作用域是必需的
- callbackUrl：结果将被提交到的URL 必需
- accessToken：从TokenService响应中获取 必需
PollingService->getStatus([ statusOpts ])：statusOpts：包含以下键的数组数组
- location：您从请求中获取的位置url 必需
- accessToken：从TokenService响应中获取 必需

这对于所有您获得位置响应的请求都适用。

有关更多信息，请参阅api-docs#polling

`SmsNotificationService`

SmsNotificationService->sendTransactionSmsNotification([ transactionNotificationOpts ])：transactionNotificationOpts：包含以下键的数组数组
- webhookEventReference：buygoods_transaction_received webhook的事件引用。
- message：要发送的消息
- callbackUrl：结果将被提交到的URL 必需
- accessToken：从TokenService响应中获取 必需
SmsNotificationService->getStatus([ statusOpts ])：statusOpts：包含以下键的数组数组
- location：您从请求中获取的位置url 必需
- accessToken：从TokenService响应中获取 必需

这对于所有您获得位置响应的请求都适用。

有关更多信息，请参阅api-docs#transaction-sms-notifications

响应和结果

除了 TokenService 之外，所有POST请求都是异步的。这意味着请求完成时，结果将被发送到您的自定义回调URL。POST请求的即时响应包含您已发送请求的 location url，您可以使用它来查询状态。

注意：异步结果是按webhook处理。

要访问响应或webhook有效负载的不同部分，请使用以下键进行访问

令牌响应

getToken()成功的响应
- acessToken
- tokenType
- expiresIn
- createdAt
introspectToken()成功的响应
- active
- scope
- clientId
- tokenType
- exp - 过期时间
- iat - 启动时间
infoToken()成功的响应
- scope
- expiresIn
- resourceOwnerId
- applicationId
- tokenType
- createdAt

Webhooks

Buygoods 收到
- id
- topic
- createdAt
- eventType
- resourceId
- reference
- originationTime
- senderPhoneNumber
- amount
- currency
- tillNumber
- system
- status
- senderFirstName
- senderMiddleName
- senderLastName
- linkSelf
- linkResource
B2b 交易收到
- id
- topic
- createdAt
- eventType
- resourceId
- reference
- originationTime
- sendingTill
- amount
- currency
- tillNumber
- system
- status
- linkSelf
- linkResource
商户到商户交易收到
- id
- topic
- createdAt
- eventType
- resourceId
- originationTime
- sendingMerchant
- amount
- currency
- status
- linkSelf
- linkResource
Buygoods 交易撤销
- id
- topic
- createdAt
- eventType
- resourceId
- reference
- originationTime
- senderPhoneNumber
- amount
- currency
- tillNumber
- system
- status
- senderFirstName
- senderMiddleName
- senderLastName
- linkSelf
- linkResource
转账完成webhook
- id
- topic
- createdAt
- eventType
- resourceId
- originationTime
- amount
- currency
- status
- 拨款
- linkSelf
- linkResource
- destinationReference
- destinationType
- 如果目的地类型是银行
  - settlementMethod
  - bankBranchRef
  - accountName
  - accountNumber
- 如果目的地类型是移动钱包
  - firstName
  - lastName
  - phoneNumber
  - network
客户创建webhook
- id
- topic
- createdAt
- eventType
- firstName
- middleName
- lastName
- phoneNumber
- linkSelf
- linkResource

结果

结算转账结果
- id
- type
- createdAt
- status
- transferBatches
- amount
- currency
- linkSelf
- callbackUrl
支付结果
- id
- type
- status
- createdAt
- transferBatches
- amount
- currency
- metadata
- linkSelf
- callbackUrl
Stk 推送结果
- 成功结果
  - id
  - type
  - initiationTime
  - status
  - eventType
  - resourceId
  - reference
  - originationTime
  - senderPhoneNumber
  - amount
  - currency
  - tillNumber
  - system
  - senderFirstName
  - senderMiddleName
  - senderLastName
  - resourceStatus
  - errors
  - metadata
  - linkSelf
  - callbackUrl
- 失败结果
  - id
  - type
  - initiationTime
  - status
  - eventType
  - resource
  - errors
  - metadata
  - linkSelf
  - callbackUrl
轮询结果
- id
- type
- status
- fromTime
- toTime
- scope
- scopeReference
- transactions
- linkSelf
- callbackUrl
交易短信通知结果
- id
- type
- status
- message
- webhookEventReference
- linkSelf
- callbackUrl

状态有效负载

Webhook 订阅状态
- id
- type
- eventType
- webhookUri
- status
- scope
- scopeReference
商户银行账户状态
- id
- type
- accountNumber
- accountName
- bankBranchRef
- settlementMethod
- status
- accountReference
商户移动钱包状态
- id
- type
- firstName
- lastName
- phoneNumber
- network
- status
- accountReference
结算转账状态
- 此有效负载类似于 SettlementTransferResult 有效负载
支付状态
- 此有效负载类似于 PaymentResult 有效负载
支付接收者状态
- id
- type
- recipientType
- status
- recipientReference
- 如果 recipientType == "Bank Account"
  - accountNumber
  - accountName
  - bankBranchRef
  - settlementMethod
- 如果 recipientType == "Mobile Wallet"
  - firstName
  - lastName
  - phoneNumber
  - network
  - email
- 如果 recipientType == "Till"
  - tillNumber
  - tillName
- 如果 recipientType == "Paybill"
  - paybillName
  - paybillNumber
  - paybillAccountNumber
Stk 推送状态
- 成功请求
  - 此有效负载类似于成功结果
- 失败请求
  - 此有效负载类似于失败结果
- 挂起请求
  - id
  - type
  - initiationTime
  - status
  - eventType
  - resource
  - errors
  - metadata
  - linkSelf
  - callbackUrl
轮询状态
- 此负载与轮询结果负载相同
交易短信通知状态
- 此负载与交易短信通知结果负载相同

错误响应

错误代码
错误消息
令牌错误响应
- 错误
- 错误描述

有关预期负载和错误代码的更多信息，请参阅API 文档

作者

Nicollet Njora

贡献

我们张开双臂欢迎各位，只需发起一个拉取请求，我们会进行审查。

开发

运行所有测试

$ composer install
$ php vendor/bin/phpunit tests --testdox

问题

如果您发现一个错误，请在GitHub上的问题跟踪器上提交一个问题。

许可证

k2-connect-php遵循MIT许可证。详细信息请参阅LICENSE。

sparkworld / laravel-kopokopo-mpesa

维护者

详细信息

README

安装

初始化

初始化后，您可以按以下方式获取提供的服务实例

使用方法

令牌

Webhooks

STK PUSH

服务

`TokenService`

`StkService`

`PayService`

`SettlementTransferService`

`PollingService`

`SmsNotificationService`

响应和结果

令牌响应

Webhooks

结果

状态有效负载

错误响应

作者

贡献

开发

问题

许可证

变更日志