fabianmuema/kopokopo

更新 kopo kopo php sdk

维护者

详细信息

github.com/fabianmuema/kopokopo

主页

源代码

问题

安装次数: 2,617

依赖项: 0

建议者: 0

安全性: 0

星标: 0

关注者: 1

分支: 2

公开问题: 0

dev-main 2023-04-01 14:18 UTC

Requires

Requires (Dev)

MIT 3e776c2d4d62e8ea12b71ac54bbf033bfe450e4a

  • Fabian Muema <muemafabian.woop@gmail.com>

This package is auto-updated.

Last update: 2024-09-30 01:43:40 UTC

README

Latest Stable Version

这是一个模块，用于帮助 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);

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

使用方法

令牌

在向 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 响应中获取 必需

有关更多信息，请参阅 https://api-docs.kopokopo.com/#receive-payments-from-m-pesa-users-via-stk-push

PayService

  • PayService->addPayRecipient([ payRecipientOptions ])：payRecipientOptions：包含以下键的数组数组

    • type：收款人类型 REQUIRED
      • 移动钱包收款人（mobile_wallet）
        • firstName：收款人名 REQUIRED
        • lastName：收款人姓 REQUIRED
        • phoneNumber：收款人电话号码 REQUIRED
        • email：收款人电子邮件地址
        • network：收款人网络 REQUIRED
      • 银行账户收款人（bank_account）
        • accountName：收款人账户名称 REQUIRED
        • accountNumber：收款人账户号码 REQUIRED
        • bankBranchRef：从kopokopo仪表板获取的银行分行参考 REQUIRED
        • settlementMethod：结算方式 REQUIRED
      • 外部收银台收款人（till）
        • tillNumber：收款人收银台号码 REQUIRED
        • tillName：收款人收银台名称 REQUIRED
      • 支付账单（paybill）
        • paybillName：收款人支付账单名称 REQUIRED
        • paybillNumber：收款人支付账单号码 REQUIRED
        • paybillAccountNumber：收款人账户号码 REQUIRED
    • accessToken：从 TokenService 响应中获取 必需

  • PayService->sendPay([ payOptions ])：payOptions：包含以下键的数组数组

    • destinationType：收款人类型 REQUIRED
    • destinationReference：收款人参考 REQUIRED
    • currency：3 位 ISO 格式的货币代码。 必需
    • amount：要收取的金额。 必需
    • callbackUrl：将结果发布到的 URL 必需
    • description：付款描述 REQUIRED
    • tags：与付款相关的标签
    • category：付款所属的分类
    • accessToken：从 TokenService 响应中获取 必需
    • metadata：它是一个包含最多 5 个键值对的最大值哈希表

  • PayService->getStatus([ location ]):

    • location：发送请求时获取的请求位置
    • accessToken：从 TokenService 响应中获取 必需

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

结算转账服务

  • SettlementTransferService->createMerchantBankAccount([ accountOpts ])：accountOpts：包含以下键的数组数组

    • accountName：结算账户名称 REQUIRED
    • bankBranchRef：结算银行分行参考 REQUIRED
    • accountNumber：结算账户号码 REQUIRED
    • settlementMethod：结算方式 REQUIRED
    • accessToken：从 TokenService 响应中获取 必需

  • SettlementTransferService->createMerchantWallet([ accountOpts ])：accountOpts：包含以下键的数组数组

    • phoneNumber：结算的电话号码 REQUIRED
    • network：结算的移动货币网络 REQUIRED
    • accessToken：从 TokenService 响应中获取 必需

  • SettlementTransferService->settleFunds([ settleOpts ])：settleOpts：包含以下键的数组数组

    • destinationType：目标类型 FOR A TARGETED TRANSFER REQUIRED
    • destinationReference：目标参考 FOR A TARGETED TRANSFER REQUIRED
    • currency：3位ISO格式货币代码。 FOR A TARGETED TRANSFER REQUIRED
    • amount：结算金额。 FOR A TARGETED TRANSFER REQUIRED PS：如果不包括，将结算全部余额。
    • accessToken：从 TokenService 响应中获取 必需

  • SettlementTransferService->getStatus([ location ]):

    • location：发送请求时获取的请求位置
    • accessToken：从 TokenService 响应中获取 必需

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

轮询服务

  • PollingService->pollTransactions([ pollingOpts ])：pollingOpts：包含以下键的数组数组

    • fromTime：轮询请求的起始时间
    • toTime：轮询请求的结束时间
    • scope：轮询请求的范围
    • scopeReference：范围参考 FOR THE 'Till' SCOPE REQUIRED
    • callbackUrl：将结果发布到的 URL 必需
    • accessToken：从 TokenService 响应中获取 必需

  • PollingService->getStatus([ statusOpts ])：statusOpts：包含以下键的数组数组

    • location：从请求中获取的位置URL REQUIRED
    • accessToken：从 TokenService 响应中获取 必需

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

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

短信通知服务

  • SmsNotificationService->sendTransactionSmsNotification([ transactionNotificationOpts ])：transactionNotificationOpts：包含以下键的数组数组

    • webhookEventReference：购买商品交易接收 webhook 的事件引用。
    • message：要发送的消息
    • callbackUrl：将结果发布到的 URL 必需
    • accessToken：从 TokenService 响应中获取 必需

  • SmsNotificationService->getStatus([ statusOpts ])：statusOpts：包含以下键的数组的数组

    • location：从请求中获取的位置URL REQUIRED
    • 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

  • 轮询结果

    • id
    • type
    • status
    • fromTime
    • toTime
    • scope
    • scopeReference
    • transactions
    • linkSelf
    • callbackUrl

  • 交易 SMS 通知结果

    • 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 结果有效负载相同

  • 交易 SMS 通知状态

    • 此有效负载与 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。

变更日志