PHPackages                             kopokopo/k2-connect-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. kopokopo/k2-connect-php

ActiveLibrary[Utility & Helpers](/categories/utility)

kopokopo/k2-connect-php
=======================

Kopokopo's php SDK

v1.4.0(4mo ago)61.4k27[1 PRs](https://github.com/kopokopo/k2-connect-php/pulls)MITPHPPHP ^7.4 || ^8.0CI failing

Since Apr 8Pushed 2mo ago11 watchersCompare

[ Source](https://github.com/kopokopo/k2-connect-php)[ Packagist](https://packagist.org/packages/kopokopo/k2-connect-php)[ Docs](https://github.com/kopokopo/k2-connect-php)[ RSS](/packages/kopokopo-k2-connect-php/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (5)Dependencies (2)Versions (11)Used By (0)

Kopokopo PHP SDK
================

[](#kopokopo-php-sdk)

[![Latest Stable Version](https://camo.githubusercontent.com/c107e42cf77ed3b3e1de73456c5c9b56719983e37b331a0ef6cba07075ced086/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6b6f706f6b6f706f2f6b322d636f6e6e6563742d706870)](https://packagist.org/packages/kopokopo/k2-connect-php)

This is a module to assist php developers in consuming Kopokopo's API

Installation
------------

[](#installation)

You can install the PHP SDK via composer.

The recommended way to install the SDK is with Composer.

```
composer require kopokopo/k2-connect-php

```

Initialisation
--------------

[](#initialisation)

The package should be configured with your client id and client secret which you can get from your account on the kopokopo's app

```
//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);
```

### After initialization, you can get instances of offered services as follows:

[](#after-initialization-you-can-get-instances-of-offered-services-as-follows)

- [Tokens](#tokenservice) : `$tokens = $K2->TokenService();`
- [Webhooks](#webhooks) : `$webhooks = $K2->Webhooks();`
- [STK PUSH](#stkservice) : `$stk = $K2->StkService();`
- [Pay](#payservice) : `$pay = $K2->PayService();`
- [Settlement Transfer](#settlementtransferservice) : `$transfer = $K2->SettlementTransferService();`
- [PollingService](#pollingservice) : `$polling = $K2->PollingService();`
- [SmsNotificationService](#smsnotificationservice) : `$sms_notification = $K2->SmsNotificationService();`

Usage
-----

[](#usage)

### Tokens

[](#tokens)

You will need to pass an access token when sending data to Kopokopo's API.

This will return `accessToken` and `expiresIn` values

```
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

[](#webhooks)

- Consuming

```
// 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);
});
```

- Subscription

```
$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-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);
```

For other usage examples check out the [example app](https://github.com/kopokopo/k2-connect-php/tree/master/example) available in this project.

Services
--------

[](#services)

The only supported ISO currency code at the moment is: `KES`

### `TokenService`

[](#tokenservice)

- `$TokenService->getToken()` to get an access token.

    - The response will have the following structure

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

NB: The access token is required to send subsequent requests

- `$TokenService->revokeToken(['accessToken' => 'myRand0mAcc3ssT0k3n'])` to revoke an access token.

NB: The access token cannot be used to send subsequent requests

- `$TokenService->introspectToken(['accessToken' => 'myRand0mAcc3ssT0k3n'])` to introspect a token.
- `$TokenService->infoToken(['accessToken' => 'myRand0mAcc3ssT0k3n'])` to get more information on a token

### `StkService`

[](#stkservice)

- `$StkService->initiateIncomingPayment([ stkOptions ])`: `stkOptions`: An array of arrays containing the following keys:

    - `tillNumber`: Your online payments short code from Kopo Kopo's Dashboard `REQUIRED`
    - `firstName`: Customer's first name
    - `lastName`: Customer's last name
    - `phoneNumber`: Phone number to pull money from. `REQUIRED`
    - `email`: Customer's email address
    - `currency`: 3-digit ISO format currency code. `REQUIRED`
    - `amount`: Amount to charge. `REQUIRED`
    - `callbackUrl`: Url that the [result](#responsesandresults) will be posted to `REQUIRED`
    - `paymentChannel`: Payment channel. Default is: `"M-PESA STK Push"`. `REQUIRED`
    - `accessToken`: Gotten from the [`TokenService`](#tokenservice) response `REQUIRED`
    - `metadata`: It is a hash containing a maximum of 5 key value pairs
- `$StkService->getStatus([location ])`:

    - `location`: The request location you get when you send a request
    - `accessToken`: Gotten from the [`TokenService`](#tokenservice) response `REQUIRED`

For more information, please read

### `PayService`

[](#payservice)

- `PayService->addPayRecipient([ payRecipientOptions ])`: `payRecipientOptions`: An array of arrays containing the following keys:

    - `type`: Recipient type `REQUIRED`
        - Mobile Wallet Recipient(`mobile_wallet`)
            - `firstName`: Pay recipient's first name `REQUIRED`
            - `lastName`: Pay recipient's last name `REQUIRED`
            - `phoneNumber`: Pay recipient's phone number `REQUIRED`
            - `email`: Pay recipient's email number
            - `network`: Pay recipient's network `REQUIRED`
        - Bank Account Recipient(`bank_account`)
            - `accountName`: Pay recipient's account name `REQUIRED`
            - `accountNumber`: Pay recipient's account number `REQUIRED`
            - `bankBranchRef`: Bank branch reference from the kopokopo dashboard `REQUIRED`
            - `settlementMethod`: Settlement method `REQUIRED`
        - External Till Recipient(`till`)
            - `tillNumber`: Pay recipient's till number `REQUIRED`
            - `tillName`: Pay recipient's till name `REQUIRED`
        - Paybill(`paybill`)
            - `paybillName`: Pay recipient's paybill name `REQUIRED`
            - `paybillNumber`: Pay recipient's paybill number `REQUIRED`
            - `paybillAccountNumber`: Pay recipient's account number `REQUIRED`
    - `accessToken`: Gotten from the [`TokenService`](#tokenservice) response `REQUIRED`
- `PayService->sendPay([ payOptions ])`: `payOptions`: An array of arrays containing the following keys:

    - `destinationType`: The recipient type. `REQUIRED`
    - `destinationReference`: The recipient reference. `REQUIRED`
    - `currency`: 3-digit ISO format currency code. `REQUIRED`
    - `amount`: Amount to charge. `REQUIRED`
    - `callbackUrl`: Url that the [result](#responsesandresults) will be posted to `REQUIRED`
    - `description`: Payment description `REQUIRED`
    - `tags`: Tags associated with the payment
    - `category`: Category that the payment belongs to
    - `accessToken`: Gotten from the [`TokenService`](#tokenservice) response `REQUIRED`
    - `metadata`: It is a hash containing a maximum of 5 key value pairs
- `PayService->getStatus([ location ])`:

    - `location`: The request location you get when you send a request
    - `accessToken`: Gotten from the [`TokenService`](#tokenservice) response `REQUIRED`

For more information, please read

### `SettlementTransferService`

[](#settlementtransferservice)

- `SettlementTransferService->createMerchantBankAccount([ accountOpts ])`: `accountOpts`: An array of arrays containing the following keys:

    - `accountName`: Settlement Account Name `REQUIRED`
    - `bankBranchRef`: Settlement Bank Branch Reference `REQUIRED`
    - `accountNumber`: Settlement account number `REQUIRED`
    - `settlementMethod`: Settlement method `REQUIRED`
    - `accessToken`: Gotten from the [`TokenService`](#tokenservice) response `REQUIRED`
- `SettlementTransferService->createMerchantWallet([ accountOpts ])`: `accountOpts`: An array of arrays containing the following keys:

    - `phoneNumber`: Phone number to settle to `REQUIRED`
    - `network`: Mobile money network to settle to `REQUIRED`
    - `accessToken`: Gotten from the [`TokenService`](#tokenservice) response `REQUIRED`
- `SettlementTransferService->settleFunds([ settleOpts ])`: `settleOpts`: An array of arrays containing the following keys:

    - `destinationType`: The destination type `REQUIRED FOR A TARGETED TRANSFER`
    - `destinationReference`: The destination reference `REQUIRED FOR A TARGETED TRANSFER`
    - `currency`: 3-digit ISO format currency code. `REQUIRED FOR A TARGETED TRANSFER`
    - `amount`: Amount to settle. `REQUIRED FOR A TARGETED TRANSFER` PS: If not included the whole balance will be settled.
    - `accessToken`: Gotten from the [`TokenService`](#tokenservice) response `REQUIRED`
- `SettlementTransferService->getStatus([ location ])`:

    - `location`: The request location you get when you send a request
    - `accessToken`: Gotten from the [`TokenService`](#tokenservice) response `REQUIRED`

For more information, please read [api-docs#transfer](https://api-docs.kopokopo.com/#transfer-to-your-account-s)

### `PollingService`

[](#pollingservice)

- `PollingService->pollTransactions([ pollingOpts ])`: `pollingOpts`: An array of arrays containing the following keys:

    - `fromTime`: The starting time of the polling request
    - `toTime`: The end time of the polling request
    - `scope`: The scope of the polling request
    - `scopeReference`: The scope reference `REQUIRED for the 'Till' scope`
    - `callbackUrl`: Url that the [result](#responsesandresults) will be posted to `REQUIRED`
    - `accessToken`: Gotten from the [`TokenService`](#tokenservice) response `REQUIRED`
- `PollingService->getStatus([ statusOpts ])`: `statusOpts`: An array of arrays containing the following keys:

    - `location`: The location url you got from the request `REQUIRED`
    - `accessToken`: Gotten from the [`TokenService`](#tokenservice) response `REQUIRED`

This works the same for all requests that you get a location response.

For more information, please read [api-docs#polling](https://api-docs.kopokopo.com/#polling)

### `SmsNotificationService`

[](#smsnotificationservice)

- `SmsNotificationService->sendTransactionSmsNotification([ transactionNotificationOpts ])`: `transactionNotificationOpts`: An array of arrays containing the following keys:

    - `webhookEventReference`: The webhook event reference for a buygoods\_transaction\_received webhook.
    - `message`: The message to be sent
    - `callbackUrl`: Url that the [result](#responsesandresults) will be posted to `REQUIRED`
    - `accessToken`: Gotten from the [`TokenService`](#tokenservice) response `REQUIRED`
- `SmsNotificationService->getStatus([ statusOpts ])`: `statusOpts`: An array of arrays containing the following keys:

    - `location`: The location url you got from the request `REQUIRED`
    - `accessToken`: Gotten from the [`TokenService`](#tokenservice) response `REQUIRED`

This works the same for all requests that you get a location response.

For more information, please read [api-docs#transaction-sms-notifications](https://api-docs.kopokopo.com/#transaction-sms-notifications)

### Responses and Results

[](#responses-and-results)

- All the post requests are asynchronous apart from `TokenService`. This means that the result will be posted to your custom callback url when the request is complete. The immediate response of the post requests contain the `location` url of the request you have sent which you can use to query the status.

Note: The asynchronous results are processed like webhooks.

- To access the different parts of the response or webhook payload passed, use the following keys to access:

#### Token Response

[](#token-response)

- getToken() successful response

    - `acessToken`
    - `tokenType`
    - `expiresIn`
    - `createdAt`
- introspectToken() successful response

    - `active`
    - `scope`
    - `clientId`
    - `tokenType`
    - `exp` - expiring time
    - `iat` - initiated at
- infoToken() successful response

    - `scope`
    - `expiresIn`
    - `resourceOwnerId`
    - `applicationId`
    - `tokenType`
    - `createdAt`

#### Webhooks

[](#webhooks-1)

- 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`
    - if destination type is bank:

        - `settlementMethod`
        - `bankBranchRef`
        - `accountName`
        - `accountNumber`
    - if destination type is mobile wallet:

        - `firstName`
        - `lastName`
        - `phoneNumber`
        - `network`
- Customer created webhook

    - `id`
    - `topic`
    - `createdAt`
    - `eventType`
    - `firstName`
    - `middleName`
    - `lastName`
    - `phoneNumber`
    - `linkSelf`
    - `linkResource`

#### Results

[](#results)

- Settlement Transfer result

    - `id`
    - `type`
    - `createdAt`
    - `status`
    - `transferBatches`
    - `amount`
    - `currency`
    - `linkSelf`
    - `callbackUrl`
- Payment result

    - `id`
    - `type`
    - `status`
    - `createdAt`
    - `transferBatches`
    - `amount`
    - `currency`
    - `metadata`
    - `linkSelf`
    - `callbackUrl`
- Stk Push Result

    - Successful result

        - `id`
        - `type`
        - `initiationTime`
        - `status`
        - `eventType`
        - `resourceId`
        - `reference`
        - `originationTime`
        - `senderPhoneNumber`
        - `amount`
        - `currency`
        - `tillNumber`
        - `system`
        - `senderFirstName`
        - `senderMiddleName`
        - `senderLastName`
        - `resourceStatus`
        - `errors`
        - `metadata`
        - `linkSelf`
        - `callbackUrl`
    - Unsuccessful result

        - `id`
        - `type`
        - `initiationTime`
        - `status`
        - `eventType`
        - `resource`
        - `errors`
        - `metadata`
        - `linkSelf`
        - `callbackUrl`
- Polling Result

    - `id`
    - `type`
    - `status`
    - `fromTime`
    - `toTime`
    - `scope`
    - `scopeReference`
    - `transactions`
    - `linkSelf`
    - `callbackUrl`
- Transaction SMS Notification Result

    - `id`
    - `type`
    - `status`
    - `message`
    - `webhookEventReference`
    - `linkSelf`
    - `callbackUrl`

#### Status Payloads

[](#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

    - This payload is similar to `SettlementTransferResult` payload
- Payment Status

    - This payload is similar to `PaymentResult` payload
- Pay Recipient Status

    - `id`
    - `type`
    - `recipientType`
    - `status`
    - `recipientReference`
    - If `recipientType == "Bank Account"`

        - `accountNumber`
        - `accountName`
        - `bankBranchRef`
        - `settlementMethod`
    - If `recipientType == "Mobile Wallet"`

        - `firstName`
        - `lastName`
        - `phoneNumber`
        - `network`
        - `email`
    - If `recipientType == "Till"`

        - `tillNumber`
        - `tillName`
    - If `recipientType == "Paybill"`

        - `paybillName`
        - `paybillNumber`
        - `paybillAccountNumber`
- Stk Push Status

    - Successful request
        - This payload is simialr to the successful result
    - Failed request
        - This payload is similar to failed result
    - Pending request
        - `id`
        - `type`
        - `initiationTime`
        - `status`
        - `eventType`
        - `resource`
        - `errors`
        - `metadata`
        - `linkSelf`
        - `callbackUrl`
- Polling Status

    - This payload is the same as the `Polling` result payload
- Transaction SMS Notification Status

    - This payload is the same as the `Transaction SMS Notification` result payload

#### Error responses

[](#error-responses)

- `errorCode`
- `errorMessage`
- Token Error Responses

    - `error`
    - `errorDescription`

For more information on the expected payloads and error codes, please read the [api docs](https://api-docs.kopokopo.com)

Author
------

[](#author)

[Nicollet Njora](https://github.com/NicoNjora)

Contributions
-------------

[](#contributions)

We welcome those with open arms just make a pull request and we will review.

### Development

[](#development)

Run all tests:

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

### Issues

[](#issues)

If you find a bug, please file an issue on [our issue tracker on GitHub](https://github.com/kopokopo/k2-connect-php/issues).

License
-------

[](#license)

k2-connect-php is MIT licensed. See [LICENSE](https://github.com/kopokopo/k2-connect-php/blob/master/LICENSE) for details.

Change log
----------

[](#change-log)

###  Health Score

52

—

FairBetter than 96% of packages

Maintenance87

Actively maintained with recent releases

Popularity27

Limited adoption so far

Community22

Small or concentrated contributor base

Maturity63

Established project with proven stability

 Bus Factor1

Top contributor holds 70.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~433 days

Total

5

Last Release

124d ago

PHP version history (2 changes)v1.3.0PHP ^7.4

v1.4.0PHP ^7.4 || ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/0972078770445eadcaa427560400f241ac1fff55c4b1513f13b567e6363720cb?d=identicon)[niconjora](/maintainers/niconjora)

![](https://www.gravatar.com/avatar/986d411d098232429e9029328055270cbb407b4d75a3a1ef203b78307b80468c?d=identicon)[dondeng](/maintainers/dondeng)

---

Top Contributors

[![NicolletNjora](https://avatars.githubusercontent.com/u/59557529?v=4)](https://github.com/NicolletNjora "NicolletNjora (80 commits)")[![NicoNjora](https://avatars.githubusercontent.com/u/25723927?v=4)](https://github.com/NicoNjora "NicoNjora (27 commits)")[![Ginger-Stone](https://avatars.githubusercontent.com/u/33225248?v=4)](https://github.com/Ginger-Stone "Ginger-Stone (5 commits)")[![dondeng](https://avatars.githubusercontent.com/u/793559?v=4)](https://github.com/dondeng "dondeng (1 commits)")[![Wambui-Mwangi](https://avatars.githubusercontent.com/u/124131028?v=4)](https://github.com/Wambui-Mwangi "Wambui-Mwangi (1 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/kopokopo-k2-connect-php/health.svg)

```
[![Health](https://phpackages.com/badges/kopokopo-k2-connect-php/health.svg)](https://phpackages.com/packages/kopokopo-k2-connect-php)
```

###  Alternatives

[shlinkio/shlink

A self-hosted and PHP-based URL shortener application with CLI and REST interfaces

4.8k4.3k](/packages/shlinkio-shlink)[ralphjsmit/laravel-helpers

A package containing handy helpers for your Laravel-application.

13704.6k2](/packages/ralphjsmit-laravel-helpers)[dhlparcel/magento2-plugin

DHL Parcel plugin for Magento 2

11180.5k2](/packages/dhlparcel-magento2-plugin)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)