K2ConnectRuby For Rails

Ruby SDK for connection to the Kopo Kopo API. This documentation gives you the specifications for connecting your systems to the Kopo Kopo Application. Primarily, the library provides functionality to do the following:

• Receive Webhook notifications.
• Receive payments from your users/customers.
• Initiate payments to third parties.
• Initiate transfers to your settlement accounts.

The library is optimized for Rails Based Frameworks. Please note, all requests MUST be made over HTTPS. Any non-secure requests are met with a redirect (HTTP 302) to the HTTPS equivalent URI. All calls made without authentication will also fail.

• Installation
• Usage
  • Authorization
  • Webhook Subscription
  • SMS Notifications
  • STK Push
  • PAY
  • Transfers
  • Polling
  • Parsing the JSON Payload
• Development
• Author
• Contributing
• License
• Changelog
• Code of Conduct

Add this line to your application's Gemfile:

gem 'k2-connect-ruby'

And then execute:

$ bundle install

Or install it yourself:

$ gem install k2-connect-ruby

Add the require line to use the gem:

require 'k2-connect-ruby'

Ensure you first Register your application with the [Kopo Kopo Sandbox](To be added later when launched). Once an application is registered you will obtain your client_id and client_secret (aka client credentials), which will be used to identify your application when calling the Kopo Kopo API.

For more Information, visit our API docs.

In order to request for application authorization and receive an access token, we need to execute the client credentials flow, this is done so by having your application server make a HTTPS request to the Kopo Kopo authorization server, through the K2AccessToken class.

k2_token = K2AccessToken.new('your_client_id', 'your_client_secret').request_token

Next, we formally create the webhook subscription by calling on the webhook_subscribe method. Ensure the following arguments are passed:

• event type REQUIRED
• url REQUIRED
• scope REQUIRED: is till if event_type is a buygoods_transaction_received, buygoods_transaction_reversed or b2b_transaction_received, and company if not
• scope reference: is REQUIRED if scope is till

Code example;

require 'k2-connect-ruby'
k2_token = K2AccessToken.new('your_client_id', 'your_client_secret').request_token
k2subscriber = K2Subscribe.new(k2_token)

your_request = {
        event_type: 'buygoods_transaction_received',
        url: callback_url,
        scope: 'till',
        scope_reference: '112233'
}
k2subscriber.webhook_subscribe(your_request)

To create an SMS notification request by calling on the send_sms_transaction_notification method. Ensure the following arguments are passed:

• webhook_event_reference REQUIRED
• message REQUIRED
• callback_url REQUIRED

Code example;

require 'k2-connect-ruby'
k2_token = K2AccessToken.new('your_client_id', 'your_client_secret').request_token
k2_notification = K2Notification.new(k2_token)

request_payload = {
        webhook_event_reference: 'c271535c-687f-4a40-a589-8b66b894792e',
        message: 'message',
        callback_url: 'callback_url'
}
k2_notification.send_sms_transaction_notification(request_payload)

To receive payments from M-PESA users via STK Push we first create a K2Stk Object, passing the access_token that was created prior.

k2_stk = K2Stk.new(your_access_token)

Afterwards we send a POST request for receiving Payments by calling the following method and passing the params value received from the POST Form Request:

k2_stk.receive_mpesa_payments(your_input)

Ensure the following arguments are passed:

• payment_channel REQUIRED
• till_number REQUIRED: from the Online Payments Account created with Kopo Kopo Inc Web App
• first_name
• last_name
• phone_number REQUIRED
• email
• currency: default is KES
• value REQUIRED
• callback_url REQUIRED

A Successful Response will be received containing the URL of the Payment Location.

To Query the STK Payment Request Status pass the Payment location URL response that is returned:

k2_stk.query_resource(k2_stk.location_url)

To Query the most recent STK Request Status is as follows:

k2_stk.query_status

As a result a JSON payload will be returned, accessible with the k2_response_body variable.

Code example;

k2_stk = K2Stk.new(your_access_token)

your_request = {
        payment_channel: 'M-PESA',
        till_number: 'K112233',
        first_name: stk_params[:first_name],
        last_name: stk_params[:last_name],
        phone_number: stk_params[:phone],
        email: stk_params[:email],
        currency: stk_params[:currency],
        value: stk_params[:value],
        callback_url: callback_url
}
k2_stk.receive_mpesa_payments(your_request)
k2_stk.query_resource(k2_stk.location_url)

First Create the K2Pay Object passing the access token

k2_pay = K2Pay.new(access_token)

Add a PAY Recipient, with the following arguments:

Mobile PAY Recipient

• type: 'mobile_wallet' REQUIRED
• first_name REQUIRED
• last_name REQUIRED
• phone_number REQUIRED
• email REQUIRED
• network REQUIRED

Bank PAY Recipient

• type: 'bank_account' REQUIRED
• account_name REQUIRED
• account_number REQUIRED
• bank_branch_ref REQUIRED
• settlement_method: 'EFT' or 'RTS' REQUIRED

Paybill PAY Recipient

• type: 'paybill' REQUIRED
• paybill_name REQUIRED
• paybill_number REQUIRED
• paybill_account_number REQUIRED

Till PAY Recipient

• type: 'till' REQUIRED

• till_name REQUIRED

• till_number REQUIRED

  k2_pay.add_recipients(your_input)

The type value can either be mobile_wallet or bank_account

A Successful Response is returned with the URL of the recipient resource.

Creating an Outgoing Payment to a third party.

k2_pay.create_payment(your_input)

The following arguments should be passed within a hash:

• destination_reference REQUIRED
• destination_type REQUIRED
• currency default is KES
• value REQUIRED
• description REQUIRED
• category
• tags
• callback_url REQUIRED

A Successful Response is returned with the URL of the Payment resource in the HTTP Location Header.

To Query the status of the Add Recipient or Outgoing Payment request:

// add recipient
k2_pay.query_resource(k2_pay.recipients_location_url)
// create outgoing payment 
k2_pay.query_resource(k2_pay.payments_location_url)

To Query the most recent status of either the Add Recipient or Outgoing Payment request:

// add recipient
k2_pay.query_status('recipients')
// create outgoing payment 
k2_pay.query_status('payments')

As a result a JSON payload will be returned, accessible with the k2_response_body variable.

Code example;

k2_pay = K2Pay.new(your_access_token)
k2_pay.add_recipient(your_recipient_input)
k2_pay.query_resource(k2_pay.recipients_location_url)

your_request = {
        destination_type: "mobile_wallet",
        destination_reference: "example_reference",
        amount: {
                "currency": "KES",
                "value": "500"
        },
        description: "k2-connect",
        category: "general",
        tags: ["tag_1", "tag_2"],
        metadata: {
                "something": "",
                "something_else": "Something else"
        },
        _links: { "callback_url": "https://example.site/example" }
}

k2_pay.create_payment(your_request)
k2_pay.query_resource(k2_pay.payments_location_url)

Add pre-approved settlement accounts, to which one can transfer funds to. Can be either a bank or mobile wallet account, with the following details:

Mobile Settlement Account

• type: 'merchant_wallet' REQUIRED
• first_name REQUIRED
• last_name REQUIRED
• phone_number REQUIRED
• network: 'Safaricom' REQUIRED

Bank Settlement Account

• type: 'merchant_bank_account' REQUIRED
• account_name REQUIRED
• account_number REQUIRED
• bank_branch_ref REQUIRED
• settlement_method: 'EFT' or 'RTS' REQUIRED

k2_settlement = K2Settlement.new(your_access_token)
# Add a mobile merchant wallet
k2_settlement.add_settlement_account(merchant_wallet)
# Add a merchant bank account
k2_settlement.add_settlement_account(merchant_bank_account)

This will Enable one to transfer funds to your settlement accounts.

First Create the K2Transfer Object

k2_transfers = K2Transfer.new(access_token)

One can either have it blind, meaning that it has no specified destination with the default/specified settlement account being selected, or one can have a targeted transfer with a specified settlement account in mind. Either can be done through:

 k2_transfers.transfer_funds(nil, params)

With nil representing that there are no specified destinations.

 k2_transfers.transfer_funds(params)

The Following Details should be passed for either Blind or Targeted Transfer:

Blind Transfer to your default settlement account

• currency default is KES
• value REQUIRED
• callback_url REQUIRED

Targeted Transfer

• destination_reference REQUIRED
• destination_type: merchant_wallet or merchant_bank_account REQUIRED
• currency default is KES
• value REQUIRED
• callback_url REQUIRED

The Params are passed as the argument containing all the form data sent. A Successful Response is returned with the URL of the transfer request in the HTTP Location Header.

Sample code example:

k2_transfer = K2Transfer.new(your_access_token)
# Blind or Targeted Transfer
k2_transfer.transfer_funds(your_input)

To Query the status of the prior initiated Transfer Request pass the location_url response as shown:

 k2_transfers.query_resource(k2_transfers.location_url)  

To Query the most recent initiated Transfer Request:

 k2_transfers.query_status  

A HTTP Response will be returned in a JSON Payload, accessible with the k2_response_body variable.

Allows you to poll transactions received on the Kopo Kopo system within a certain time range, and either a company or a specific till.

First Create the K2Notification Object

k2_notification = K2Notification.new(access_token)

The Following Details should be passed for creating the notification:

• fromTime REQUIRED
• toTime REQUIRED
• scope REQUIRED
• scopeReference REQUIRED
• callback_url REQUIRED

The Params are passed as the argument containing all the form data sent. A Successful Response is returned with the URL of the request in the HTTP Location Header.

Sample code example:

k2_notification = K2Notification.new(your_access_token)
# Blind or Targeted Transfer
k2_notification.send_sms_transaction_notification(request_payload)

To Query the status of the prior initiated Notification Request pass the location_url response as shown:

 k2_notification.query_resource_url(k2_notification.location_url)  

To Query the most recent initiated Transfer Request:

 k2_notification.query_resource  

A HTTP Response will be returned in a JSON Payload, accessible with the k2_response_body variable.

The K2Client class will be use to parse the Payload received from Kopo Kopo, and to further consume the webhooks and split the responses into components, the K2Authenticator and K2ProcessResult Classes will be used.

First Create an Object of the K2Client class to Parse the response, passing the client_secret_key received from Kopo Kopo:

 k2_parse = K2Client.new(client_secret)

 k2_parse.parse_request(request)

Create an Object to receive the components resulting from processing the parsed request results which will be returned by the following method:

 k2_components = K2ProcessResult.process(k2_parse.hash_body)

Code example:

k2_parse = K2Client.new(client_secret)
k2_parse.parse_request(request)
k2_components = K2ProcessResult.process(k2_parse.hash_body)

Below is a list of key symbols accessible for each of the Results retrieved after processing it into an Object.

1. Buy Goods Transaction Received:

   • id
   • resource_id
   • topic
   • created_at
   • event_type
   • reference
   • origination_time
   • sender_phone_number
   • amount
   • currency
   • till_number
   • system
   • status
   • sender_first_name
   • sender_last_name
   • links_self
   • links_resource

2. Buy Goods Transaction Reversed:

   • id
   • resource_id
   • topic
   • created_at
   • event_type
   • reference
   • origination_time
   • sender_phone_number
   • amount
   • currency
   • till_number
   • system
   • status
   • sender_first_name
   • sender_last_name
   • links_self
   • links_resource

3. Settlement Transfer:

   • id
   • resource_id
   • topic
   • created_at
   • event_type
   • origination_time
   • amount
   • currency
   • resource_status
   • links_self
   • links_resource
   • destination_reference
   • destination_type Bank Account Destination Type
   • destination_account_name
   • destination_account_number
   • destination_bank_branch_ref
   • destination_settlement_method Merchant Wallet Destination Type
   • destination_first_name
   • destination_last_name
   • destination_phone_number
   • destination_network

4. Customer Created:

   • id
   • resource_id
   • topic
   • created_at
   • event_type
   • resource_first_name
   • resource_middle_name
   • resource_last_name
   • resource_phone_number
   • links_self
   • links_resource

5. B2b Transaction Transaction (External Till to Till):

   • id
   • resource_id
   • topic
   • created_at
   • event_type
   • reference
   • origination_time
   • amount
   • currency
   • till_number
   • status
   • links_self
   • links_resource
   • sending_till

6. Process STK Push Payment Request Result

   • id
   • type
   • initiation_time
   • status
   • event_type
   • resource_id
   • resource_status
   • transaction_reference
   • origination_time
   • sender_phone_number
   • amount
   • currency
   • till_number
   • system
   • sender_first_name
   • sender_middle_name
   • sender_last_name
   • errors
   • metadata
   • links_self
   • callback_url

7. Process PAY Result

   • id
   • type
   • created_at
   • status
   • transfer_batch
   • currency
   • value
   • metadata
   • links_self
   • callback_url

8. Process Settlement Transfer Result

   • id
   • type
   • created_at
   • status
   • transfer_batch
   • currency
   • value
   • links_self
   • callback_url

If you want to convert the Object into a Hash or Array, the following methods can be used.

• Hash:

    k2_hash_components = K2ProcessResult.return_obj_hash(k2_components)
  

• Array:

    k2_array_components = K2ProcessResult.return_obj_array(k2_components)
  

Sample Web Application examples written in Rails and Sinatra frameworks that utilize this library are available in the example_app folder or in the following GitHub hyperlinks:

• Rails example application

• Sinatra example application

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Name: David Kariuki Mwangi

Bug reports and pull requests are welcome on GitHub at https://github.com/kopokopo/k2-connect-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

The gem is available as open source under the terms of the [MIT License].

Everyone interacting in the K2ConnectRuby project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.