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 : $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' => 'http://localhost: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' => 'http://localhost: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)
    - paybillName：收款人的支付账单名称 必需
    - paybillNumber：收款人的支付账单号码 必需
    - 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：您从请求中获得的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：您从请求中获得的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 Received
- id
- topic
- createdAt
- eventType
- resourceId
- reference
- originationTime
- senderPhoneNumber
- amount
- currency
- tillNumber
- system
- status
- senderFirstName
- senderMiddleName
- senderLastName
- linkSelf
- linkResource
B2b transaction received
- id
- topic
- createdAt
- eventType
- resourceId
- reference
- originationTime
- sendingTill
- amount
- currency
- tillNumber
- system
- status
- linkSelf
- linkResource
Merchant to merchant transaction received
- id
- topic
- createdAt
- eventType
- resourceId
- originationTime
- sendingMerchant
- amount
- currency
- status
- linkSelf
- linkResource
Buygoods transaction reversed
- id
- topic
- createdAt
- eventType
- resourceId
- reference
- originationTime
- senderPhoneNumber
- amount
- currency
- tillNumber
- system
- status
- senderFirstName
- senderMiddleName
- senderLastName
- linkSelf
- linkResource
Transfer completed webhook
- id
- topic
- createdAt
- eventType
- resourceId
- originationTime
- amount
- currency
- status
- disbursements
- linkSelf
- linkResource
- destinationReference
- destinationType
- 如果目的地类型是银行
  - settlementMethod
  - bankBranchRef
  - accountName
  - accountNumber
- 如果目的地类型是移动钱包
  - firstName
  - lastName
  - phoneNumber
  - network
Customer created 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
Polling 结果
- id
- type
- status
- fromTime
- toTime
- scope
- scopeReference
- transactions
- linkSelf
- callbackUrl
Transaction SMS Notification 结果
- id
- type
- status
- message
- webhookEventReference
- linkSelf
- callbackUrl

Status Payloads

Webhook Subscription Status
- id
- type
- eventType
- webhookUri
- status
- scope
- scopeReference
Merchant Bank Account Status
- id
- type
- accountNumber
- accountName
- bankBranchRef
- settlementMethod
- status
- accountReference
Merchant Mobile Wallet Status
- id
- type
- firstName
- lastName
- phoneNumber
- network
- status
- accountReference
Settlement Transfer Status
- 此有效负载类似于SettlementTransferResult有效负载
Payment Status
- 此有效负载类似于PaymentResult有效负载
Pay Recipient Status
- 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 Status
- 成功请求
  - 此有效负载类似于成功结果
- 失败请求
  - 此有效负载类似于失败结果
- 挂起请求
  - id
  - type
  - initiationTime
  - status
  - eventType
  - resource
  - errors
  - metadata
  - linkSelf
  - callbackUrl
Polling Status
- 此有效负载与Polling结果有效负载相同
Transaction SMS Notification Status
- 此有效负载与Transaction SMS Notification结果有效负载相同

错误响应

错误码
错误信息
令牌错误响应
- 错误
- 错误描述

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

作者

Nicollet Njora

贡献

我们热烈欢迎大家，只需发起一个拉取请求，我们将会进行审查。

开发

运行所有测试

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

问题

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

许可证

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

kopokopo / k2-connect-php

维护者

详细信息

README

安装

初始化

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

用法

令牌

Webhooks

STK PUSH

服务

`TokenService`

`StkService`

`PayService`

`SettlementTransferService`

`PollingService`

`SmsNotificationService`

响应和结果

令牌响应

Webhooks

结果

Status Payloads

错误响应

作者

贡献

开发

问题

许可证

变更日志