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' => '[email protected]',
                '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

Issues

If you find a bug, please file an issue on our issue tracker on GitHub.

License

k2-connect-php is MIT licensed. See LICENSE for details.

Change log