README

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

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();
External Recipient : $externalRecipientService = $K2->ExternalRecipientService();
Settlement Transfer : $transfer = $K2->SettlementTransferService();
SendMoneyService : $sendMoney = $K2->SendMoneyService();
PollingService : $polling = $K2->PollingService();
ReversalService: reversalService = $K2->ReversalService();
PaymentLinkService: paymentLinkService = $K2->PaymentLinkService();

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',
    'enableDarajaPayload' => 'false'
]);

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 available in this project.

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

`ExternalRecipientService`

ExternalRecipientService->addExternalRecipient([ externalRecipientOptions ]): externalRecipientOptions: 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
ExternalRecipientService->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

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

`SendMoneyService`

SendMoneyService->sendMoney([ sendMoneyOptions ]): sendMoneyOptions: An associative array containing the following keys:
- destinations: An array of nested associative arrays defining destination details.
- currency: 3-digit ISO format currency code. REQUIRED
- sourceIdentifier: The source of funds to transfer, i.e, till number or null for available balance.
- metadata: It is a hash containing a maximum of 5 key-value pairs.
- callbackUrl: URL that the result will be posted to. REQUIRED
- accessToken: Gotten from the TokenService response. REQUIRED
SendMoneyService->getStatus([ statusOptions ]): statusOptions: An associative array containing the following keys:
- location: The request location you get when you send a request. REQUIRED
- accessToken: Gotten from the TokenService response. REQUIRED
For more information, please read api-docs#send_money

`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

`ReversalService`

ReversalService->initiateReversal([ reversalOptions ]): reversalOptions: An associative array containing the following keys:
- transactionReference: Reference of the transaction to be reversed. REQUIRED
- reason: Reason for the reversal. REQUIRED
- metadata: An associative array with a maximum of 5 key-value pairs.
- callbackUrl: URL that the result will be posted to. REQUIRED
- accessToken: Gotten from the TokenService response. REQUIRED
ReversalServices->getStatus([ statusOptions ]): statusOptionsAn associative array containing the following keys:
- location: The request location you get when you initiate a reversal request. REQUIRED
- accessToken: Gotten from the TokenService response. REQUIRED

`PaymentLinkService`

PaymentLinkService->createPaymentLink([ paymentLinkOptions ]): paymentLinkOptions: An associative array containing the following keys:
- tillNumber: Till number for the M-PESA or Online Payments Account that will receive the payment. REQUIRED
- currency: 3-digit ISO format currency code. REQUIRED
- amount: The amount the customer will pay. REQUIRED
- paymentReference: The merchant internal reference for the payment.
- note: Note for the customer as they make the payment.
- metadata: An associative array with a maximum of 5 key pairs.
- callbackUrl: URL that the payment link result will be posted to once a customer makes a payment. REQUIRED
- accessToken: Gotten from the TokenService response. REQUIRED
PaymentLinkService->cancelPaymentLink([ cancellationOptions ]): cancellationOptions: An associative array containing the following keys:
- location: The request location you get when you send a payment link request. REQUIRED
- accessToken: Gotten from the TokenService response. REQUIRED
PaymentLinkService->getStatus([ statusOptions ]): statusOptions: An associative array containing the following keys:
- location: The request location you get when you send a payment link request. REQUIRED
- accessToken: Gotten from the TokenService response. REQUIRED

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

Send Money Result
- id
- type
- createdAt
- status
- sourcedIdentifier
- destinations
- currency
- transferBatches
- errors
- 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
Reversal Result
- id
- type
- transactionReference
- status
- reason
- reversalBulkPayment
- errors
- metadata
- createdAt
- callbackUrl
- linkSelf
Payment Link Result
- id
- type
- status
- currency
- amount
- tillName
- tillNumber
- paymentReference
- note
- createdAt
- paymentLink
- errors
- metadata
- callbackUrl
- linkSelf

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
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
Send Money Status
- This payload is similar to Send Money Result payload
Stk Push Status
- Successful request
  - This payload is similar 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
Reversal Status
- This payload is similar to Reversal Result payload
Payment Link Status
- This payload is similar to Payment Link 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

kopokopo / k2-connect-php

Maintainers

Package info

Statistics

Security

README

Installation

Initialisation

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

Usage

Tokens

Webhooks

STK PUSH

Services

`TokenService`

`StkService`

`ExternalRecipientService`

`SettlementTransferService`

`SendMoneyService`

`PollingService`

`ReversalService`

`PaymentLinkService`

Responses and Results

Token Response

Webhooks

Results

Status Payloads

Error responses

Author

Contributions

Development

Issues

License

Change log