kopokopo/k2-connect-php

v1.0.0 2021-04-08 06:12 UTC

This package is auto-updated.

Last update: 2021-04-08 16:46:52 UTC


README

Latest Stable Version

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:

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: Amount to charge. 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

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
      • Kopo Kopo Merchant(kopo_kopo_merchant)
        • tillNumber: Pay recipient's till number REQUIRED
        • aliasName: Pay recipient's alias name 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: Amount to charge. REQUIRED
    • 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

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

For more information, please read api-docs#transfer

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

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 == "Kopo Kopo Merchant"

      • tillNumber
      • aliasName
  • 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

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