README

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

安装

您可以通过composer安装PHP SDK。

推荐使用Composer安装SDK。

composer require kopokopo/k2-connect-php

初始化

应使用您的客户端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();
轮询服务 : $polling = $K2->PollingService();
短信通知服务 : $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：结算金额。 目标转账必填 PS：如不包含，则将结算全部余额。
- 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
- disbursements
- 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 Push 结果
- 成功结果
  - 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 Push 状态
- 成功请求
  - 此有效载荷类似于成功结果
- 失败请求
  - 此有效载荷类似于失败结果
- 挂起请求
  - id
  - type
  - initiationTime
  - status
  - eventType
  - resource
  - errors
  - metadata
  - linkSelf
  - callbackUrl
轮询状态
- 此有效载荷与 Polling 结果有效载荷相同
交易短信通知状态
- 此有效载荷与 Transaction SMS Notification 结果有效载荷相同

错误响应

errorCode
errorMessage
令牌错误响应
- error
- errorDescription

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

作者

Nicollet Njora

贡献

我们热情欢迎各位，只需发起一个pull request，我们会进行审查。

开发

运行所有测试

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

问题

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

许可证

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

dedanirungu / k2-connect-php

维护者

详细信息

README

安装

初始化

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

用法

令牌

Webhooks

STK PUSH

服务

`TokenService`

`StkService`

`PayService`

`SettlementTransferService`

`PollingService`

`SmsNotificationService`

响应和结果

令牌响应

Webhooks

结果

状态有效载荷

错误响应

作者

贡献

开发

问题

许可证

变更日志