k2-connect-ruby 3.1.0 → 4.0.0

data/README.md

@@ -8,8 +8,10 @@ Primarily, the library provides functionality to do the following:
 
  - Receive Webhook notifications.
  - Receive payments from your users/customers.
+ - Initiate reversals for payments from your users/customers
  - Initiate payments to third parties.
- - Initiate transfers to your settlement accounts.
+ - Initiate transfers to your preferred accounts.
+ - Create payment links
  
 The library is optimized for **Rails Based Frameworks**.
 Please note, all requests MUST be made over HTTPS.
@@ -22,12 +24,13 @@ All calls made without authentication will also fail.
  - [Usage](#installation)
     - [Authorization](#authorization)
     - [Webhook Subscription](#webhook-subscription)
-    - [SMS Notifications](#sms-notifications)
     - [STK Push](#stk-push)
-    - [PAY](#pay)
-    - [Settlemennt accounts](#settlement-accounts)
-    - [Transfers](#transfers)
+    - [Add External recipients](#add-external-recipients)
+    - [Add Transfer accounts](#add-transfer-accounts)
+    - [Send money](#send-money)
     - [Polling](#polling)
+    - [Reversals](#reversals)
+    - [Payment links](#payment-links)
     - [Parsing the JSON Payload](#parsing-the-json-payload)
  - [Development](#development)
  - [Author](#author)
@@ -59,14 +62,17 @@ Add the require line to use the gem:
 To set the base_url:
 
 ```ruby
-K2ConnectRuby::K2Utilities::Config::K2Config.set_base_url("https://sandbox.kopokopo.com/")
+K2ConnectRuby::K2Utilities::Config::K2Config.base_url = "https://sandbox.kopokopo.com/"
 ```
 
-To set the api version:
+> [!NOTE]
+> The API version in use is K2 Connect v2. To use K2 Connect v2, make use of versions 3.0.0 of the SDK. 
 
-```ruby
-K2ConnectRuby::K2Utilities::Config::K2Config.set_version(1)
-```
+> [!WARNING]
+> The following APIs are deprecated on version 2 (v2).
+> - Pay (Replaced with Send money)
+> - Transfers (Replaced with Send money)
+> - SMS Notifications
 
 ### Authorization
 
@@ -78,7 +84,7 @@ 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.
 
 ```ruby
-k2_token = K2ConnectRuby::K2Entity::K2Token.new('your_client_id', 'your_client_secret').request_token
+access_token = K2ConnectRuby::K2Entity::K2Token.new('your_client_id', 'your_client_secret').request_token
 ```
 
 ### Webhook Subscription
@@ -89,58 +95,49 @@ Next, we formally create the webhook subscription by calling on the webhook_subs
 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
+ - scope `REQUIRED`: is `till` if event_type is a buygoods_transaction_received, buygoods_transaction_reversed, b2b_transaction_received, card_transaction_received, card_transaction_voided or card_transaction_reversed and `company` if not
+ - scope_reference: is `REQUIRED` if scope is till
+ - enable_daraja_payload: `OPTIONAL`. By default, it is set to `false`
+
+Supported event types:
+- buygoods_transaction_received
+- buygoods_transaction_reversed
+- b2b_transaction_received
+- b2b_transaction_reversed
+- card_transaction_received
+- card_transaction_voided
+- card_transaction_reversed
+- customer_created
+- settlement_transfer_completed
  
 Code example;
 
 ```ruby
 require 'k2-connect-ruby'
-k2_token = K2ConnectRuby::K2Entity::K2Token.new('your_client_id', 'your_client_secret').request_token
-k2subscriber = K2ConnectRuby::K2Entity::K2Subscribe.new(k2_token)
+access_token = K2ConnectRuby::K2Entity::K2Token.new('your_client_id', 'your_client_secret').request_token
+k2subscriber = K2ConnectRuby::K2Entity::K2Subscribe.new(access_token)
 your_request = {
   event_type: 'buygoods_transaction_received',
   url: callback_url,
   scope: 'till',
-  scope_reference: '112233'
+  scope_reference: '112233',
+  enable_daraja_payload: true
 }
 k2subscriber.webhook_subscribe(your_request)
 ```
 
-### SMS Notifications
-
-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;
-
-```ruby
-require 'k2-connect-ruby'
-k2_token = K2ConnectRuby::K2Entity::K2Token.new('your_client_id', 'your_client_secret').request_token
-k2_notification = K2ConnectRuby::K2Entity::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)
-```
-
  
 ### STK-Push
  
- #### Receive Payments
+#### Receive Payments
  
  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 = K2ConnectRuby::K2Entity::K2Stk.new(your_access_token)
+    k2_stk = K2ConnectRuby::K2Entity::K2Stk.new(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)
+    k2_stk.send_stk_request(your_input)
     
 Ensure the following arguments are passed:
  - payment_channel `REQUIRED`
@@ -149,7 +146,7 @@ Ensure the following arguments are passed:
  - last_name 
  - phone_number `REQUIRED`
  - email
- - currency: default is `KES`
+ - currency: `KES` expected
  - value `REQUIRED`
  - callback_url `REQUIRED`
 
@@ -170,35 +167,38 @@ As a result a JSON payload will be returned, accessible with the k2_response_bod
 Code example;
     
 ```ruby
-k2_stk = K2ConnectRuby::K2Entity::K2Stk.new(your_access_token)
+k2_stk = K2ConnectRuby::K2Entity::K2Stk.new(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
+  payment_channel: "M-PESA STK Push",
+  till_number: "K112233",
+  first_name: "First",
+  middle_name: "Middle",
+  last_name: "Last",
+  phone_number: "phone_number",
+  email: "test_email@email.com",
+  currency: "KES",
+  amount: "100",
+  metadata: {
+    customer_id: "123_456_789",
+    reference: "123_456",
+    notes: "Placeholder text",
+  },
+  callback_url: callback_url,
 }
-k2_stk.receive_mpesa_payments(your_request)
+k2_stk.send_stk_request(your_request)
 k2_stk.query_resource(k2_stk.location_url)
 ```
 
-### PAY
-
-First Create the K2Pay Object passing the access token
+### Add External Recipients
 
+First Create the `ExternalRecipient` Object passing the access token
 
-    k2_pay = K2ConnectRuby::K2Entity::K2Pay.new(access_token)
+    external_recipient = K2ConnectRuby::K2Entity::ExternalRecipient.new(access_token)
 
-#### Add PAY Recipients
+Add a external recipient, with the following arguments:
 
-Add a PAY Recipient, with the following arguments:
-
-**Mobile** PAY Recipient
+**Mobile** External Recipient
 - type: 'mobile_wallet' `REQUIRED`
 - first_name `REQUIRED`
 - last_name `REQUIRED`
@@ -206,182 +206,271 @@ Add a PAY Recipient, with the following arguments:
 - email `REQUIRED`
 - network `REQUIRED`
 
-**Bank** PAY Recipient
+**Bank** External Recipient
 - type: 'bank_account' `REQUIRED`
 - account_name `REQUIRED`
 - account_number `REQUIRED`
 - bank_branch_ref `REQUIRED`
-- settlement_method: 'EFT' or 'RTS' `REQUIRED`
 
-**Paybill** PAY Recipient
+**Paybill** External Recipient
 - type: 'paybill' `REQUIRED`
 - paybill_name `REQUIRED`
 - paybill_number `REQUIRED`
 - paybill_account_number `REQUIRED`
 
-**Till** PAY Recipient
+**Till** External Recipient
 - type: 'till' `REQUIRED`
 - till_name `REQUIRED`
 - till_number `REQUIRED`
 
 ```ruby
-k2_pay.add_recipients(your_input)
+external_recipient = K2ConnectRuby::K2Entity::ExternalRecipient.new(access_token)
+your_input = {
+  type: "mobile_wallet",
+  first_name: "First",
+  last_name: "Last",
+  email: "test_email@email.com",
+  phone_number: "phone_number",
+}
+external_recipient.add_external_recipient(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.
-
-#### Create Outgoing Payment
+The type value can be `mobile_wallet`, `bank_account`, `till` or `paybill`
 
-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 recipient resource.
 
-A Successful Response is returned with the URL of the Payment resource in the HTTP Location Header.
+#### Query add ExternalRecipient Request Status
 
-#### Query PAY Request Status
+To Query the status of the Add Recipient:
 
-To Query the status of the Add Recipient or Outgoing Payment request:
+    external_recipient.query_resource(external_recipient.recipients_location_url)
 
-    // 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 the Add Recipient:
 
-To Query the most recent status of either the Add Recipient or Outgoing Payment request:
+    external_recipient.query_status
 
-    // add recipient
-    k2_pay.query_status('recipients')
-    // create outgoing payment 
-    k2_pay.query_status('payments')
+A HTTP Response will be returned in a JSON Payload, accessible with the k2_response_body variable.
 
-As a result a JSON payload will be returned, accessible with the k2_response_body variable.
- 
 Code example;
-    
-```ruby
-k2_pay = K2ConnectRuby::K2Entity::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)
+```ruby
+external_recipient = K2ConnectRuby::K2Entity::ExternalRecipient.new(access_token)
+external_recipient.add_external_recipient(your_input)
+external_recipient.query_resource(external_recipient.recipients_location_url)
 ```
 
-### Settlement Accounts
+### Add Transfer Accounts
 
-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:
+Add pre-approved transfer accounts, to which one can transfer funds to. Can be either a bank or mobile wallet account,
+with the following details:
 
-**Mobile** Settlement Account
+**Mobile** Transfer Account
 - type: 'merchant_wallet' `REQUIRED`
 - first_name `REQUIRED`
 - last_name `REQUIRED`
 - phone_number `REQUIRED`
 - network: 'Safaricom' `REQUIRED`
+- nickname
+- email
 
-**Bank** Settlement Account
+**Bank** Transfer Account
 - type: 'merchant_bank_account' `REQUIRED`
 - account_name `REQUIRED`
 - account_number `REQUIRED`
 - bank_branch_ref `REQUIRED`
 - settlement_method: 'EFT' or 'RTS' `REQUIRED`
+- nickname
 
 ```ruby
-k2_settlement = K2ConnectRuby::K2Entity::K2Settlement.new(your_access_token)
+transfer_account = K2ConnectRuby::K2Entity::TransferAccount.new(access_token)
 # Add a mobile merchant wallet
-k2_settlement.add_settlement_account(merchant_wallet)
+merchant_wallet_params = {
+  type: "merchant_wallet",
+  first_name: "first_name",
+  last_name: "last_name",
+  email: "email@email.com",
+  phone_number: "phone_number",
+  nickname: "nickname",
+}
+transfer_account.add_transfer_account(merchant_wallet_params)
 # Add a merchant bank account
-k2_settlement.add_settlement_account(merchant_bank_account)
+merchant_bank_account_params = {
+  type: "merchant_bank_account",
+  account_name: Faker::Name.name_with_middle,
+  account_number: Faker::Number.number(digits: 10),
+  bank_branch_ref: "reference to bank branch", # View https://developers.kopokopo.com/ on how to retrieve the bank branch reference
+  settlement_method: "EFT",
+  nickname: Faker::Name.name_with_middle,
+}
+transfer_account.add_transfer_account(merchant_bank_account_params)
 ```
 
-### Transfers
+A Successful Response is returned with the URL of the resource.
 
-This will Enable one to transfer funds to your settlement accounts.
+#### Query add transfer account Request Status
 
-First Create the K2Transfer Object
+To Query the status of the Add Transfer account:
 
-    k2_transfers =  K2ConnectRuby::K2Entity::K2Transfer.new(access_token)
+    transfer_account.query_resource(transfer_account.transfer_account_location_url)
 
-#### Create Transfer Request
+To Query the most recent status of the Add Transfer account:
 
-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:
+    transfer_account.query_status
 
-##### Blind Transfer
+A HTTP Response will be returned in a JSON Payload, accessible with the k2_response_body variable.
 
-     k2_transfers.transfer_funds(params)
+Code example;
 
-With `nil` representing that there are no specified destinations.
+```ruby
+transfer_account = K2ConnectRuby::K2Entity::TransferAccount.new(access_token)
+transfer_account.add_transfer_account(your_input)
+transfer_account.query_resource(transfer_account.transfer_account_location_url)
+```
 
-##### Target Transfer
+### Send money
 
-     k2_transfers.transfer_funds(params)
-      
-The Following Details should be passed for either **Blind** or **Targeted** Transfer:
+First Create the `SendMoney` Object passing the access token
 
-**Blind** Transfer to your default settlement account
-- currency default is `KES`
-- value `REQUIRED`
-- callback_url `REQUIRED`
+    send_money = K2ConnectRuby::K2Entity::SendMoney.new(access_token)
+
+Creating an Outgoing Payment to a third party.
 
-**Targeted** Transfer
-- destination_reference `REQUIRED`
-- destination_type: `merchant_wallet` or `merchant_bank_account` `REQUIRED`
-- currency default is `KES`
-- value `REQUIRED`
+    send_money.create_payment(your_input)
+    
+The following arguments should be passed within a hash:
+
+- destinations (array of hashes). `REQUIRED` unless doing send money sweep of available funds
+- currency `KES` expected
+- source_identifier
 - 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.
+The hash structure within the destinations array:
 
-Sample code example:
+Send to **External Mobile Recipient**
+- type: 'mobile_wallet' `REQUIRED`
+- phone_number `REQUIRED`
+- amount `REQUIRED`
+- description `REQUIRED`
+- network `REQUIRED`
+- first_name
+- last_name
+- nickname
+- favourite
 
-```ruby
-k2_transfer =  K2ConnectRuby::K2Entity::K2Transfer.new(your_access_token)
-# Blind or Targeted Transfer
-k2_transfer.transfer_funds(your_input)
-```
+Send to **External Bank account Recipient**
+- type: 'bank_account' `REQUIRED`
+- account_name `REQUIRED`
+- account_number `REQUIRED`
+- amount `REQUIRED`
+- description `REQUIRED`
+- bank_branch_ref `REQUIRED`
+- nickname
+- favourite
+
+Send to **External Paybill Recipient**
+- type: 'paybill' `REQUIRED`
+- paybill_number `REQUIRED`
+- paybill_account_number `REQUIRED`
+- paybill_name
+- description `REQUIRED`
+- nickname
+- favourite
 
-#### Query Prior Transfer
+Send to **External Till Recipient**
+- type: 'till' `REQUIRED`
+- till_number `REQUIRED`
+- till_name
+- description `REQUIRED`
+- nickname
+- favourite
 
-To Query the status of the prior initiated Transfer Request pass the location_url response as shown:
+Send to **My Mobile Phone**
+- type: 'merchant_wallet' `REQUIRED`
+- reference `REQUIRED`
+- amount `REQUIRED`
 
-     k2_transfers.query_resource(k2_transfers.location_url)  
+Send to **My Bank account**
+- type: 'merchant_bank_account' `REQUIRED`
+- reference `REQUIRED`
+- amount `REQUIRED`
 
-To Query the most recent initiated Transfer Request:
+A Successful Response is returned with the URL of the Payment resource in the HTTP Location Header.
 
-     k2_transfers.query_status  
+#### Query SendMoney Request Status
+
+To Query the status of the Outgoing Payment request:
+
+    send_money.query_resource(send_money.payments_location_url)
+
+To Query the most recent status of Outgoing Payment request:
+ 
+    send_money.query_status
 
 A HTTP Response will be returned in a JSON Payload, accessible with the k2_response_body variable.
+ 
+Code example of send money to an external recipient;
+
+```ruby
+# Send money to external recipient
+params = {
+  destinations: [
+    {
+      type: "bank_account",
+      bank_branch_ref: "reference to bank branch", # View https://developers.kopokopo.com/ on how to retrieve the bank branch reference
+      account_name: Faker::Name.name,
+      account_number: "bank account number",
+      nickname: Faker::Name.name,
+      amount: "1000",
+      description: "send money via K2 Connect",
+    },
+  ],
+  currency: "KES",
+  source_identifier: nil,
+  metadata: {
+    order_no: "ORD192832",
+  },
+  callback_url: Faker::Internet.url,
+}
+access_token = K2ConnectRuby::K2Entity::K2Token.new("client_id", "client_secret").request_token
+send_money = K2ConnectRuby::K2Entity::SendMoney.new(access_token)
+send_money.create_payment(params)
+```
+
+Code example of send money to a transfer account;
+
+```ruby
+# Send money to a transfer account
+params = {
+  destinations: [
+    {
+      type: "merchant_wallet",
+      reference: destination_reference, # Retrieved from logging into the merchant app https://app.kopokopo.com
+      amount: "1000",
+    },
+  ],
+  currency: "KES",
+  source_identifier: nil,
+  callback_url: callback_url,
+}
+access_token = K2ConnectRuby::K2Entity::K2Token.new("client_id", "client_secret").request_token
+send_money = K2ConnectRuby::K2Entity::SendMoney.new(access_token)
+send_money.create_payment(params)
+```
+
+Code example of send money to my accounts (Sweep all available funds);
+
+```ruby
+# Send money to my accounts
+params = {
+  destinations: [],
+  currency: "KES",
+  source_identifier: nil,
+  callback_url: callback_url,
+}
+access_token = K2ConnectRuby::K2Entity::K2Token.new("client_id", "client_secret").request_token
+send_money = K2ConnectRuby::K2Entity::SendMoney.new(access_token)
+send_money.create_payment(params)
+```
 
 ### Polling
 
@@ -394,7 +483,7 @@ First Create the K2Polling Object
 The following details should be passed:
 
 - scope `REQUIRED`
-- scope_reference
+- scope_reference is `REQUIRED` if scope is till
 - from_time `REQUIRED`
 - to_time `REQUIRED`
 - callback_url `REQUIRED`
@@ -402,32 +491,159 @@ The following details should be passed:
 Sample code example:
 
 ```ruby
-your_input =
-        {
-                scope: "company",
-                scope_reference: "",
-                from_time: "2021-04-12T08:50:22+03:00",
-                to_time: "2021-04-19T08:50:22+03:00",
-                callback_url: 'https://call_back_to_your_app.your_application.com'
-        }
-
-k2_polling = K2ConnectRuby::K2Entity::K2Polling.new("your_access_token")
+your_input = {
+  scope: "company",
+  scope_reference: "",
+  from_time: "2025-04-12T08:50:22+03:00",
+  to_time: "2025-04-19T08:50:22+03:00",
+  callback_url: 'http://placeholder_url_com'
+}
+
+k2_polling = K2ConnectRuby::K2Entity::K2Polling.new("access_token")
 k2_polling.poll(your_input)
 k2_polling.location_url # => "https://sandbox.kopokopo.com/api/v1/polling/247b1bd8-f5a0-4b71-a898-f62f67b8ae1c"
 ```
 
 #### Query Request
 
-To Query the status of the prior initiated Notification Request pass the location_url response as shown:
+To Query the status of the prior initiated Polling Request pass the location_url response as shown:
 
-     k2_notification.query_resource_url(k2_notification.location_url)  
+     k2_polling.query_resource_url(k2_polling.location_url)  
 
-To Query the most recent initiated Transfer Request:
+To Query the most recent initiated Polling Request:
 
-     k2_notification.query_resource  
+     k2_polling.query_resource  
 
 A HTTP Response will be returned in a JSON Payload, accessible with the k2_response_body variable.
 
+### Reversals
+
+Initiate a reversal for a C2B or B2B transaction to your till and get the reversal request's status.
+
+#### Initiate a reversal
+Create an instance of `K2ConnectRuby::K2Entity::Reversal` object and call `initiate_reversal` method with the following reversal parameters:
+- `transaction_reference`: Reference of the transaction to be reversed. `REQUIRED`
+- `reason`: Reason for the reversal. `REQUIRED`
+- `metadata`: A hash with a maximum of 5 key-value pairs.
+- `callback_url`: URL that the result will be posted to. `REQUIRED`
+
+```ruby
+reversal_params = {
+  transaction_reference: "Y7T2990R11",
+  reason: "Erroneous payment",
+  metadata: {
+    order_no: "ORD192832",
+  },
+  callback_url: "https://example.com/callback",
+}
+
+access_token = K2ConnectRuby::K2Entity::K2Token.new("client_id", "client_secret").request_token
+k2_reversal = K2ConnectRuby::K2Entity::Reversal.new(access_token)
+k2_reversal.initiate_reversal(reversal_params)
+```
+
+
+#### Get status of reversal request
+```ruby
+reversal_params = {
+  transaction_reference: "Y7T2990R11",
+  reason: "Erroneous payment",
+  metadata: {
+    order_no: "ORD192832",
+  },
+  callback_url: "https://example.com/callback",
+}
+
+access_token = K2ConnectRuby::K2Entity::K2Token.new("client_id", "client_secret").request_token
+k2_reversal = K2ConnectRuby::K2Entity::Reversal.new(access_token)
+location_url = k2_reversal.initiate_reversal(reversal_params)
+
+# Get status of current reversal request
+k2_reversal.query_status
+
+# Get status of specific reversal request
+k2_reversal.query_resource(location_url)
+```
+
+### Payment Links
+
+Generate a payment link that you can share with a customer to collect a payment
+
+#### Create a payment link
+Create an instance of `K2ConnectRuby::K2Entity::PaymentLink` object and call `create_payment_link` method with the following payment link parameters:
+- `till_number`:  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`
+- `payment_reference`: The merchant internal reference for the payment.
+- `note`: Note for the customer as they make the payment.
+- `metadata`: A hash with a maximum of 5 key pairs.
+- `callback_url`: URL that the payment link result will be posted to once a customer makes a payment. `REQUIRED`
+
+```ruby
+payment_link_params = {
+  till_number: "4321",
+  currency: "KES",
+  amount: 1000,
+  payment_reference: "INV02932922",
+  note: "Payment for monthly internet subscription",
+  metadata: {
+    account_number: "1234567",
+  },
+  callback_url: "https://example.com/callback",
+}
+
+access_token = K2ConnectRuby::K2Entity::K2Token.new("client_id", "client_secret").request_token
+k2_payment_links = K2ConnectRuby::K2Entity::PaymentLink.new(access_token)
+k2_payment_links.create_payment_link(payment_link_params)
+```
+
+### Cancel payment link
+```ruby
+payment_link_params = {
+  till_number: "4321",
+  currency: "KES",
+  amount: 1000,
+  payment_reference: "INV02932922",
+  note: "Payment for monthly internet subscription",
+  metadata: {
+    account_number: "1234567",
+  },
+  callback_url: "https://example.com/callback",
+}
+
+access_token = K2ConnectRuby::K2Entity::K2Token.new("client_id", "client_secret").request_token
+k2_payment_links = K2ConnectRuby::K2Entity::PaymentLink.new(access_token)
+location_url = k2_payment_links.create_payment_link(payment_link_params)
+
+# Cancel payment link
+k2_payment_links.cancel_payment_link(location_url)
+```
+
+#### Get status of payment link
+```ruby
+payment_link_params = {
+  till_number: "4321",
+  currency: "KES",
+  amount: 1000,
+  payment_reference: "INV02932922",
+  note: "Payment for monthly internet subscription",
+  metadata: {
+    account_number: "1234567",
+  },
+  callback_url: "https://example.com/callback",
+}
+
+access_token = K2ConnectRuby::K2Entity::K2Token.new("client_id", "client_secret").request_token
+k2_payment_links = K2ConnectRuby::K2Entity::PaymentLink.new(access_token)
+location_url = k2_payment_links.create_payment_link(payment_link_params)
+
+# Get status of current payment link
+k2_payment_links.query_status
+
+# Get status of specific payment link
+k2_payment_links.query_resource(location_url)
+```
+
 ### Parsing the JSON Payload
 
 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
@@ -472,6 +688,7 @@ k2_components = K2ConnectRuby::K2Utilities::K2ProcessResult.process(k2_parse.has
     - `reference`
     - `origination_time`
     - `sender_phone_number`
+    - `hashed_sender_phone`
     - `amount`
     - `currency`
     - `till_number`
@@ -499,8 +716,8 @@ k2_components = K2ConnectRuby::K2Utilities::K2ProcessResult.process(k2_parse.has
     - `sender_first_name`
     - `sender_last_name`
     - `links_self`
-    - `links_resource` 
-    
+    - `links_resource`
+
 3. Settlement Transfer:
     - `id`
     - `resource_id`
@@ -539,7 +756,23 @@ k2_components = K2ConnectRuby::K2Utilities::K2ProcessResult.process(k2_parse.has
     - `links_self`
     - `links_resource`
     
-5. B2b Transaction Transaction (External Till to Till):
+5. B2b Transaction Received (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. B2B Transaction Reversed:
     - `id`
     - `resource_id`
     - `topic`
@@ -554,8 +787,57 @@ k2_components = K2ConnectRuby::K2Utilities::K2ProcessResult.process(k2_parse.has
     - `links_self`
     - `links_resource`
     - `sending_till`
+
+7. Card Transaction Received
+    - `id`
+    - `resource_id`
+    - `topic`
+    - `created_at`
+    - `event`
+    - `reference`
+    - `origination_time`
+    - `amount`
+    - `currency`
+    - `till_number`
+    - `customer_cc_number`
+    - `status`
+    - `links_self`
+    - `links_resource`
+    - `settled`
+
+8. Card Transaction Reversed:
+    - `id`
+    - `resource_id`
+    - `topic`
+    - `created_at`
+    - `event`
+    - `reference`
+    - `origination_time`
+    - `amount`
+    - `currency`
+    - `till_number`
+    - `customer_cc_number`
+    - `status`
+    - `links_self`
+    - `links_resource`
+
+9. Card Transaction Voided:
+   - `id`
+   - `resource_id`
+   - `topic`
+   - `created_at`
+   - `event_type`
+   - `reference`
+   - `origination_time`
+   - `amount`
+   - `currency`
+   - `till_number`
+   - `customer_cc_number`
+   - `status`
+   - `links_self`
+   - `links_resource`
     
-6. Process STK Push Payment Request Result
+10. Process STK Push Payment Request Result
     - `id`
     - `type`
     - `initiation_time`
@@ -578,7 +860,7 @@ k2_components = K2ConnectRuby::K2Utilities::K2ProcessResult.process(k2_parse.has
     - `links_self`
     - `callback_url`
 
-7. Process PAY Result
+11. Process Send money Result
     - `id`
     - `type`
     - `created_at`
@@ -590,17 +872,36 @@ k2_components = K2ConnectRuby::K2Utilities::K2ProcessResult.process(k2_parse.has
     - `links_self`
     - `callback_url`
 
-8. Process Settlement Transfer Result
-   - `id`
-   - `type`
-   - `created_at`
-   - `status`
-   - `transfer_batch`
-   - `currency`
-   - `value`
-   - `links_self`
-   - `callback_url`
-    
+12. Reversal Result
+    - `id`
+    - `type`
+    - `transaction_reference`
+    - `status`
+    - `created_at`
+    - `reason`
+    - `reversal_bulk_payment`
+    - `errors`
+    - `metadata`
+    - `callback_url`
+    - `links_self`
+
+13. Payment Link Result
+    - `id`
+    - `type`
+    - `status`
+    - `created_at`
+    - `till_name`
+    - `till_number`
+    - `payment_reference`
+    - `currency`
+    - `amount`
+    - `note`
+    - `payment_link`
+    - `errors`
+    - `metadata`
+    - `callback_url`
+    - `links_self`
+
 If you want to convert the Object into a Hash or Array, the following methods can be used.
 - Hash:
    
@@ -620,7 +921,7 @@ Sample Web Application examples written in Rails and Sinatra frameworks that uti
 
  - [Sinatra example application](https://github.com/DavidKar1uk1/kt_tips)
  
- ##### Take Note; the Library is optimized for Rails frameworks version 5.
+ ##### Take Note; the Library is optimized for Rails frameworks version 8.
 
 ## Development