Suq Kopokopo PHP SDK

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

... updated php unit and guzzle

composer require suq/suq-k2-connect-php:dev-master

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

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:

Tokens : $tokens = $K2->TokenService();
Webhooks : $webhooks = $K2->Webhooks();
STK PUSH : $stk = $K2->StkService();
Pay : $pay = $K2->PayService();
Settlement Transfer : $transfer = $K2->SettlementTransferService();
PollingService : $polling = $K2->PollingService();
SmsNotificationService : $sms_notification = $K2->SmsNotificationService();

Usage

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

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 = $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.

Services

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

`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->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 will be posted to REQUIRED
- paymentChannel: Payment channel. Default is: "M-PESA STK Push". REQUIRED
- accessToken: Gotten from the 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 response REQUIRED

For more information, please read https://api-docs.kopokopo.com/#receive-payments-from-m-pesa-users-via-stk-push

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

For more information, please read https://api-docs.kopokopo.com/#send-money-pay

`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 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 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 response REQUIRED
SettlementTransferService->getStatus([ location ]):
- location: The request location you get when you send a request
- accessToken: Gotten from the TokenService response REQUIRED

For more information, please read api-docs#transfer

`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 will be posted to REQUIRED
- accessToken: Gotten from the 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 response REQUIRED

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

For more information, please read api-docs#polling

`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 will be posted to REQUIRED
- accessToken: Gotten from the 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 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

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

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

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

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

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

errorCode
errorMessage
Token Error Responses
- error
- errorDescription

For more information on the expected payloads and error codes, please read the api docs

Author

Nicollet Njora

Contributions

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

Development

Run all tests:

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

britisharmy/suq-k2-connect-php

Suq Kopokopo PHP SDK

Installation

Initialisation

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

Usage

Tokens

Webhooks

STK PUSH

Services

`TokenService`

`StkService`

`PayService`

`SettlementTransferService`

`PollingService`

`SmsNotificationService`

Responses and Results

Token Response

Webhooks

Results

Status Payloads

Error responses

Author

Contributions

Development

Issues

License

Change log