mpesa_stk 2.0.0 → 3.0.0

data/README.md

@@ -1,219 +1,219 @@
 # MpesaStk
 
-Copyright (c) 2018 mboya
+Ruby client for [Safaricom Daraja](https://developer.safaricom.co.ke/) APIs: Lipa na M-Pesa (STK Push), B2C/B2B/C2B, transaction queries, standing orders (Ratiba), IoT SIM portal, IMSI checks, and pull transactions.
 
-MIT License
+[![Gem Version](https://badge.fury.io/rb/mpesa_stk.svg)](https://badge.fury.io/rb/mpesa_stk)
+[![Cop](https://github.com/mboya/mpesa_stk/actions/workflows/cop.yml/badge.svg?branch=master)](https://github.com/mboya/mpesa_stk/actions/workflows/cop.yml)
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+**Version 3.0** — unified `.call` API with keyword options. Upgrading from 2.x? See [MIGRATION.md](MIGRATION.md).
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
-
----
-
-A comprehensive Ruby gem for integrating with Safaricom's M-Pesa APIs, IoT services, and related payment solutions. This gem provides easy-to-use interfaces for STK Push, B2C, B2B, C2B, transaction queries, standing orders, IoT SIM management, and more.
-
-[![Gem Version](https://badge.fury.io/rb/mpesa_stk.svg)](https://badge.fury.io/rb/mpesa_stk.svg)
-![Cop](https://github.com/mboya/mpesa_stk/workflows/Cop/badge.svg?branch=master)
+**Requirements:** Ruby >= 2.6, [Redis](https://redis.io/) (OAuth tokens are cached per consumer key)
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add to your Gemfile:
 
 ```ruby
 gem 'mpesa_stk'
 ```
-and run the `bundle install` command
-
-Or install it yourself as:
-```ruby
-gem install mpesa_stk
-```
 
-# Getting Started
+Then:
 
-## Prerequisites
-
-**Redis:** This gem has a [Redis](https://redis.io/) dependency, so make sure it's running:
 ```bash
-$ redis-server
+bundle install
 ```
 
-You can verify Redis is running:
+Or install directly:
+
 ```bash
-$ redis-cli ping
-# Should return: PONG
+gem install mpesa_stk
 ```
 
-**Bundler:** Ensure you have a recent version of bundler (2.4+ recommended for Ruby 3.3+):
+## Configuration
+
+Copy the sample environment file and fill in your Daraja credentials:
+
 ```bash
-$ gem install bundler
-$ bundle --version  # Should show 2.4.0 or higher
+cp .sample.env .env
 ```
 
-> **Note:** If you see deprecation warnings about `Gem::Platform.match` or `DidYouMean::SPELL_CHECKERS`, update bundler with `gem install bundler`. These warnings come from older bundler versions and don't affect gem functionality.
+`require 'mpesa_stk'` loads `.env` via Dotenv when present (skip with `ENV['MPESA_STK_SKIP_DOTENV'] = 'true'` in Rails and similar apps).
+
+Override settings in code:
 
-you need to setup your environment variables, checkout `.sample.env` for the values you need.
-or run
 ```ruby
-$ cp .sample.env .env
+MpesaStk.configure do |c|
+  c[:key] = 'your_consumer_key'
+  c[:secret] = 'your_consumer_secret'
+  c[:business_short_code] = '174379'
+  c[:business_passkey] = 'your_passkey'
+  c[:callback_url] = 'https://your.app/mpesa/callback'
+end
 ```
-open `.env` on your editor and add the missing variables. See `.sample.env` for all available configuration options.
 
-**Required for STK Push:**
-* `key` and `secret` - Consumer key and secret from your [developer account](https://developer.safaricom.co.ke/user/me/apps)
-* `business_short_code` and `business_passkey` - Found in [Test Credentials](https://developer.safaricom.co.ke/test_credentials)
-* `callback_url` - Your webhook URL for receiving payment confirmations (must be HTTPS and reachable)
+| Variable | Purpose |
+|----------|---------|
+| `base_url` | API host (sandbox or production) |
+| `key`, `secret` | Consumer key and secret |
+| `business_short_code`, `business_passkey` | STK / PayBill credentials |
+| `callback_url` | STK Push callback |
+| `confirmation_url` | C2B confirmation URL |
+| `till_number` | Buy Goods till |
+| `initiator`, `initiator_name`, `security_credential` | B2C/B2B/status/balance/reversal |
+| `result_url`, `queue_timeout_url` | Async result endpoints |
+| `iot_api_key`, `vpn_group`, `username` | IoT portal (optional) |
 
-**Required for B2C/B2B/Reversal/Transaction Status:**
-* `initiator` or `initiator_name` - API user name
-* `security_credential` - Encrypted initiator password (use Safaricom's public key)
-* `result_url` - Webhook URL for async results
-* `queue_timeout_url` - Webhook URL for timeout notifications
+Endpoint paths (`process_request_url`, `b2c_url`, etc.) default to sandbox values in `.sample.env`. Change `base_url` and paths when moving to production.
 
-**For C2B:**
-* `confirmation_url` - URL for payment confirmations
+**Redis** must be running locally (default `redis://127.0.0.1:6379`). `MpesaStk::AccessToken` stores and refreshes bearer tokens automatically.
 
-**For IoT APIs:**
-* `iot_api_key` - API key for IoT services (default provided for sandbox)
-* `vpn_group` - VPN group identifier
-* `username` - Username for IoT operations
+## Quick start
 
-`Prod:`
+STK Push (PayBill) — one line when `.env` is configured:
 
-when going live there information will be sent to your email.
+```ruby
+require 'mpesa_stk'
 
-for `buy_goods` push  `business_short_code` will be equivalent to `store number` and `till_number` will remain as is.
+response = MpesaStk::Push.call(100, '254712345678')
+# => { "ResponseCode" => "0", "CheckoutRequestID" => "ws_CO_...", ... }
+```
 
-### Testing out the gem in an actual Rails application
+Register your `callback_url` and handle the STK result on your server ([STK Push](#stk-push)).
 
-To test out the app on an actual rails application, do check out the following link:
+## Usage
 
-https://github.com/mboya/stk
+Every client exposes a **single entry point**:
 
-```shell
-  https://github.com/mboya/stk
-```
-#### Sample application
-Check out a rails sample application [here](https://github.com/mboya/stk)
+- `.call(...)` for payments and queries
+- `.register(...)` for URL registration (C2B, pull transactions)
 
-### Quick Start Examples
+Pass **keyword options** to override `.env` for a request (credentials, short codes, URLs):
 
-**Single App (using ENV variables):**
 ```ruby
-$ irb
-> require 'mpesa_stk'
-> MpesaStk::PushPayment.call("500", "254711222333")
+MpesaStk::Push.call(
+  100,
+  '254712345678',
+  business_short_code: '174379',
+  business_passkey: 'your_passkey',
+  callback_url: 'https://your.app/callback',
+  key: 'consumer_key',
+  secret: 'consumer_secret'
+)
 ```
 
-**Multiple Apps (using hash parameters):**
-```ruby
-$ irb
-> require 'mpesa_stk'
-> hash = {
-    "key" => "your_key",
-    "secret" => "your_secret",
-    "business_short_code" => "174379",
-    "business_passkey" => "your_passkey",
-    "callback_url" => "https://your-app.com/callback",
-    "till_number" => "174379"
-  }
-> MpesaStk::Push.pay_bill("500", "254711222333", hash)      # Pay Bill
-> MpesaStk::Push.buy_goods("500", "254711222333", hash)    # Till Number
-```
+| Intent | Call |
+|--------|------|
+| STK PayBill (default) | `Push.call(amount, phone)` |
+| STK Buy Goods | `Push.call(amount, phone, type: :buy_goods)` |
+| B2C payout | `B2C.call(amount, phone)` |
+| STK status | `StkPushQuery.call(checkout_request_id)` |
 
-> **Note:** For complete API documentation with all available endpoints, response formats, and detailed examples, see the [API Reference](#api-reference) and [Response Format & Error Handling](#response-format--error-handling) sections below.
+## Understanding responses
 
-### Mpesa Checkout/Express
+Every successful API call returns a **parsed `Hash`** (JSON keys as strings). In most Daraja APIs, `"ResponseCode" => "0"` means the request was **accepted for processing**, not that money has already moved.
 
-After initiating an STK Push, the customer will see a payment prompt on their phone. This is the expected output:
+| Layer | Who delivers it | Your action |
+|-------|-----------------|-------------|
+| **Synchronous** | Returned by the gem immediately | Store IDs (`CheckoutRequestID`, `ConversationID`, etc.) |
+| **Callback** | Safaricom `POST` to your HTTPS URL | Update orders, wallets, logs; always respond HTTP 200 |
+| **Query** | Optional follow-up (`StkPushQuery`, pull API) | Poll when you did not receive a callback |
 
-![alt tag](./bin/index.jpeg)
+On HTTP errors the gem raises `StandardError` with status and body, for example:
 
-### Callback URL Requirements
+```json
+{
+  "errorCode": "400.001.1001",
+  "errorMessage": "Bad Request"
+}
+```
 
-Before implementing callbacks, note these requirements:
-- **HTTPS Required**: All callback URLs must use HTTPS (not HTTP)
-- **Publicly Accessible**: Your callback URLs must be reachable from the internet
-- **Response Expected**: Your endpoint should return HTTP 200 OK to acknowledge receipt
-- **Timeout**: Safaricom expects a response within 30 seconds
+Sandbox and production payloads follow the same shape; values differ. Confirm against [official Daraja docs](https://developer.safaricom.co.ke/Documentation) when integrating a new API version.
 
-## API Reference
+## API reference
 
-### STK Push (Lipa na M-Pesa Online)
+| Class | Entry point | Notes |
+|-------|-------------|--------|
+| `MpesaStk::Push` | `.call(amount, phone, type: :pay_bill \| :buy_goods, **options)` | STK Push; PayBill is default |
+| `MpesaStk::StkPushQuery` | `.call(checkout_request_id, **options)` | STK payment status |
+| `MpesaStk::B2C` | `.call(amount, phone, **options)` | Business → customer |
+| `MpesaStk::B2B` | `.call(amount, receiver_party, **options)` | Business → business |
+| `MpesaStk::C2B` | `.register(**options)`, `.call(amount, phone, **options)` | URL registration & sandbox simulate |
+| `MpesaStk::TransactionStatus` | `.call(transaction_id, **options)` | Transaction status query |
+| `MpesaStk::AccountBalance` | `.call(**options)` | Balance (async via `result_url`) |
+| `MpesaStk::Reversal` | `.call(transaction_id, amount, **options)` | Reverse a transaction |
+| `MpesaStk::Ratiba` | `.call(amount:, party_a:, start_date:, end_date:, **options)` | Standing orders |
+| `MpesaStk::PullTransactions` | `.register(**options)`, `.call(start, end, **options)` | Pull transactions |
+| `MpesaStk::IMSI` | `.call(customer_number, version: 'v1', **options)` | IMSI / SIM swap check |
+| `MpesaStk::IoT` | `.list_sims`, `.send_message`, `.call(:method, ...)` | IoT SIM portal |
+| `MpesaStk::AccessToken` | `.call(key, secret)` | OAuth token (usually internal) |
+
+Phone numbers use international format without `+`, e.g. `254712345678`.
+
+---
 
-Initiates a payment prompt on the customer's phone. The customer receives an STK push notification and can complete the payment by entering their M-Pesa PIN. This is the same technique the mySafaricom App uses for payments.
+### STK Push (`MpesaStk::Push`)
+
+`MpesaStk::Push` replaces the former `PushPayment` and `Push` classes from 2.x.
+
+**PayBill** (default) — uses `business_short_code` as `PartyB`:
 
-**Single App (using ENV variables):**
 ```ruby
-result = MpesaStk::PushPayment.call("500", "254712345678")
+MpesaStk::Push.call(100, '254712345678')
 ```
 
-**Multiple Apps (using hash parameters):**
+**Buy Goods** — requires `till_number` in `.env` or as a keyword:
+
 ```ruby
-hash = {
-  "key" => "your_key",
-  "secret" => "your_secret",
-  "business_short_code" => "174379",
-  "business_passkey" => "your_passkey",
-  "callback_url" => "https://your-app.com/callback"
-}
+MpesaStk::Push.call(100, '254712345678', type: :buy_goods)
+MpesaStk::Push.call(100, '254712345678', type: :buy_goods, till_number: '174379')
+```
 
-# Pay Bill
-result = MpesaStk::Push.pay_bill("500", "254712345678", hash)
+**Per-request overrides** (multi-app or custom credentials):
 
-# Buy Goods (Till Number)
-hash["till_number"] = "174379"
-result = MpesaStk::Push.buy_goods("500", "254712345678", hash)
+```ruby
+MpesaStk::Push.call(
+  100,
+  '254712345678',
+  business_short_code: '174379',
+  business_passkey: 'your_passkey',
+  callback_url: 'https://your.app/callback',
+  key: 'consumer_key',
+  secret: 'consumer_secret'
+)
 ```
 
-**Query STK Push Status:**
-
-Check the status of an STK Push transaction using the CheckoutRequestID returned from the initial STK Push request.
+**Immediate response**:
 
-```ruby
-# Using ENV variables
-result = MpesaStk::StkPushQuery.query("ws_CO_DMZ_40472724_16062018092359957")
-
-# Using hash parameters
-result = MpesaStk::StkPushQuery.query("ws_CO_DMZ_40472724_16062018092359957", {
-  "business_short_code" => "174379",
-  "business_passkey" => "your_passkey"
-})
+```json
+{
+  "MerchantRequestID": "7909-1302368-1",
+  "CheckoutRequestID": "ws_CO_DMZ_40472724_16062018092359957",
+  "ResponseCode": "0",
+  "ResponseDescription": "Success. Request accepted for processing",
+  "CustomerMessage": "Success. Request accepted for processing"
+}
 ```
 
-**STK Push Callbacks:**
+Persist `CheckoutRequestID` to match the callback and STK query.
 
-After the customer enters their PIN on the checkout/express prompt, you will receive a POST request on your `callback_url` with the transaction status.
+**Callback** (Safaricom `POST` to `callback_url` — not returned by the gem):
 
-**Sample Callback Payload:**
-```ruby
+Success:
+
+```json
 {
-  "Body" => {
-    "stkCallback" => {
-      "MerchantRequestID" => "3968-94214-1",
-      "CheckoutRequestID" => "ws_CO_160620191218268004",
-      "ResultCode" => 0,
-      "ResultDesc" => "The service request is processed successfully.",
-      "CallbackMetadata" => {
-        "Item" => [
-          {"Name" => "Amount", "Value" => "05"},
-          {"Name" => "MpesaReceiptNumber", "Value" => "OFG4Z5EE9Y"},
-          {"Name" => "TransactionDate", "Value" => 20190616121848},
-          {"Name" => "PhoneNumber", "Value" => 254711222333}
+  "Body": {
+    "stkCallback": {
+      "MerchantRequestID": "7909-1302368-1",
+      "CheckoutRequestID": "ws_CO_DMZ_40472724_16062018092359957",
+      "ResultCode": 0,
+      "ResultDesc": "The service request is processed successfully.",
+      "CallbackMetadata": {
+        "Item": [
+          { "Name": "Amount", "Value": 100 },
+          { "Name": "MpesaReceiptNumber", "Value": "QK4A1B2C3D" },
+          { "Name": "TransactionDate", "Value": 20250125143000 },
+          { "Name": "PhoneNumber", "Value": 254712345678 }
         ]
       }
     }
@@ -221,866 +221,382 @@ After the customer enters their PIN on the checkout/express prompt, you will rec
 }
 ```
 
-**Result Codes:**
-- `0` - Success
-- `1032` - Request cancelled by user
-- `1037` - Timeout waiting for user input
-- `2001` - Insufficient balance
-- Other codes indicate various error conditions
-
-### Transaction Status Query
-
-Query the status of any M-Pesa transaction using the transaction ID (M-Pesa Receipt Number). Useful for checking if a payment was successful, failed, or is still pending.
-
-```ruby
-# Using ENV variables
-result = MpesaStk::TransactionStatus.query("OFR4Z5EE9Y")
-
-# Using hash parameters
-result = MpesaStk::TransactionStatus.query("OFR4Z5EE9Y", {
-  "initiator" => "testapi",
-  "security_credential" => "encrypted_credential",
-  "result_url" => "https://your-app.com/result",
-  "queue_timeout_url" => "https://your-app.com/timeout"
-})
-```
-
-**Transaction Status Callbacks:**
+Failed or cancelled (no `CallbackMetadata`; common `ResultCode` values: `1032` cancelled, `1037` timeout):
 
-Transaction status queries send results to `result_url` and `queue_timeout_url`.
-
-**Sample Result Callback Payload:**
-```ruby
+```json
 {
-  "Result" => {
-    "ResultType" => 0,
-    "ResultCode" => 0,
-    "ResultDesc" => "The service request is processed successfully.",
-    "OriginatorConversationID" => "12345-67890-1",
-    "ConversationID" => "AG_20200101_00001234567890",
-    "TransactionID" => "LGR123456789",
-    "ResultParameters" => {
-      "ResultParameter" => [
-        {"Key" => "TransactionStatus", "Value" => "Completed"},
-        {"Key" => "TransactionAmount", "Value" => "100.00"},
-        {"Key" => "TransactionReceipt", "Value" => "LGR123456789"},
-        {"Key" => "B2CWorkingAccountAvailableFunds", "Value" => "50000.00"},
-        {"Key" => "B2CUtilityAccountAvailableFunds", "Value" => "100000.00"},
-        {"Key" => "TransactionCompletedDateTime", "Value" => "01.01.2020 12:00:00"},
-        {"Key" => "ReceiverPartyPublicName", "Value" => "254712345678 - John Doe"}
-      ]
+  "Body": {
+    "stkCallback": {
+      "MerchantRequestID": "7909-1302368-1",
+      "CheckoutRequestID": "ws_CO_DMZ_40472724_16062018092359957",
+      "ResultCode": 1032,
+      "ResultDesc": "Request cancelled by user."
     }
   }
 }
 ```
 
-### B2C (Business to Customer)
-
-Send money from a business account to a customer's mobile money account. Commonly used for salary payments, refunds, cashback, or any business-to-customer disbursements. The customer receives the money directly in their M-Pesa account.
+---
 
-**Using ENV variables:**
-```ruby
-# Set ENV variables: initiator_name, security_credential, result_url, queue_timeout_url
-result = MpesaStk::B2C.pay("500", "254712345678", {
-  "command_id" => "BusinessPayment", # or "SalaryPayment", "PromotionPayment"
-  "remarks" => "Payment for services",
-  "occasion" => "Optional occasion" # optional
-})
-```
+### STK Push query
 
-**Using hash parameters:**
 ```ruby
-result = MpesaStk::B2C.pay("500", "254712345678", {
-  "key" => "your_key",
-  "secret" => "your_secret",
-  "initiator_name" => "testapi",
-  "security_credential" => "encrypted_credential",
-  "command_id" => "BusinessPayment", # or "SalaryPayment", "PromotionPayment"
-  "remarks" => "Payment for services",
-  "occasion" => "Optional occasion", # optional
-  "result_url" => "https://your-app.com/result",
-  "queue_timeout_url" => "https://your-app.com/timeout"
-})
+MpesaStk::StkPushQuery.call('ws_CO_DMZ_40472724_16062018092359957')
 ```
 
-**B2C Callbacks:**
-
-B2C payments send results to two callback URLs:
-- **Result URL** (`result_url`): Receives transaction results (success or failure)
-- **Queue Timeout URL** (`queue_timeout_url`): Receives timeout notifications
+**Immediate response** (accepted query; payment outcome is in `ResultCode`):
 
-**Sample Result Callback Payload:**
-```ruby
+```json
 {
-  "Result" => {
-    "ResultType" => 0,
-    "ResultCode" => 0,
-    "ResultDesc" => "The service request is processed successfully.",
-    "OriginatorConversationID" => "12345-67890-1",
-    "ConversationID" => "AG_20200101_00001234567890",
-    "TransactionID" => "LGR123456789",
-    "ResultParameters" => {
-      "ResultParameter" => [
-        {"Key" => "TransactionAmount", "Value" => "100.00"},
-        {"Key" => "TransactionReceipt", "Value" => "LGR123456789"},
-        {"Key" => "B2CRecipientIsRegisteredCustomer", "Value" => "Y"},
-        {"Key" => "B2CChargesPaidAccountAvailableFunds", "Value" => "-100.00"},
-        {"Key" => "ReceiverPartyPublicName", "Value" => "254712345678 - John Doe"},
-        {"Key" => "TransactionCompletedDateTime", "Value" => "01.01.2020 12:00:00"},
-        {"Key" => "B2CUtilityAccountAvailableFunds", "Value" => "50000.00"},
-        {"Key" => "B2CWorkingAccountAvailableFunds", "Value" => "100000.00"}
-      ]
-    },
-    "ReferenceData" => {
-      "ReferenceItem" => [
-        {"Key" => "QueueTimeoutURL", "Value" => "https://your-app.com/timeout"}
-      ]
-    }
-  }
+  "ResponseCode": "0",
+  "ResponseDescription": "The service request is processed successfully.",
+  "MerchantRequestID": "7909-1302368-1",
+  "CheckoutRequestID": "ws_CO_DMZ_40472724_16062018092359957",
+  "ResultCode": "0",
+  "ResultDesc": "The service request is processed successfully."
 }
 ```
 
-**Result Codes:**
-- `0` - Success
-- `1` - Insufficient balance
-- `2` - Less than minimum transaction value
-- `4` - More than maximum transaction value
-- `5` - Would exceed daily transfer limit
-- `6` - Would exceed minimum balance
-- `8` - Customer account not found
-- `11` - Timeout
+When the customer has not completed payment you may see non-zero `ResultCode` (e.g. `499` pending). Plan to combine query results with the callback for a single source of truth.
 
-### B2B (Business to Business)
+---
 
-Send money from one business account to another business account. Used for business-to-business payments such as supplier payments, service payments, or inter-business transfers. Supports both PayBill and Till Number recipients.
+### B2C
 
-**Using ENV variables:**
 ```ruby
-# Set ENV variables: initiator, security_credential, result_url, queue_timeout_url
-# Pay Bill
-result = MpesaStk::B2B.pay("1000", "123456", {
-  "command_id" => "BusinessPayBill", # or "BusinessBuyGoods", "DisburseFundsToBusiness"
-  "receiver_identifier_type" => "4" # "4" for paybill, "2" for till
-})
-
-# Buy Goods
-result = MpesaStk::B2B.pay("1000", "987654", {
-  "command_id" => "BusinessBuyGoods",
-  "receiver_identifier_type" => "2"
-})
+MpesaStk::B2C.call(100, '254712345678', command_id: 'BusinessPayment', remarks: 'Salary')
 ```
 
-**Using hash parameters:**
-```ruby
-# Pay Bill
-result = MpesaStk::B2B.pay("1000", "123456", {
-  "key" => "your_key",
-  "secret" => "your_secret",
-  "initiator" => "testapi",
-  "security_credential" => "encrypted_credential",
-  "command_id" => "BusinessPayBill",
-  "receiver_identifier_type" => "4",
-  "result_url" => "https://your-app.com/result",
-  "queue_timeout_url" => "https://your-app.com/timeout"
-})
-
-# Buy Goods
-result = MpesaStk::B2B.pay("1000", "987654", {
-  "key" => "your_key",
-  "secret" => "your_secret",
-  "initiator" => "testapi",
-  "security_credential" => "encrypted_credential",
-  "command_id" => "BusinessBuyGoods",
-  "receiver_identifier_type" => "2",
-  "result_url" => "https://your-app.com/result",
-  "queue_timeout_url" => "https://your-app.com/timeout"
-})
-```
+**Immediate response:**
 
-**B2B Callbacks:**
+```json
+{
+  "ResponseCode": "0",
+  "ResponseDescription": "The service request is processed successfully.",
+  "OriginatorConversationID": "12345-67890-1",
+  "ConversationID": "AG_20240101_12345678901234567890"
+}
+```
 
-Similar to B2C, B2B payments use `result_url` and `queue_timeout_url` for callbacks.
+**Callback** (`result_url` / `queue_timeout_url`):
 
-**Sample Result Callback Payload:**
-```ruby
+```json
 {
-  "Result" => {
-    "ResultType" => 0,
-    "ResultCode" => 0,
-    "ResultDesc" => "The service request is processed successfully.",
-    "OriginatorConversationID" => "12345-67890-1",
-    "ConversationID" => "AG_20200101_00001234567890",
-    "TransactionID" => "LGR123456789",
-    "ResultParameters" => {
-      "ResultParameter" => [
-        {"Key" => "TransactionAmount", "Value" => "1000.00"},
-        {"Key" => "TransactionReceipt", "Value" => "LGR123456789"},
-        {"Key" => "B2BWorkingAccountAvailableFunds", "Value" => "50000.00"},
-        {"Key" => "ReceiverPartyPublicName", "Value" => "600000 - Company Name"},
-        {"Key" => "TransactionCompletedDateTime", "Value" => "01.01.2020 12:00:00"},
-        {"Key" => "B2BUtilityAccountAvailableFunds", "Value" => "100000.00"}
+  "Result": {
+    "ResultType": 0,
+    "ResultCode": 0,
+    "ResultDesc": "The service request is processed successfully.",
+    "OriginatorConversationID": "12345-67890-1",
+    "ConversationID": "AG_20240101_12345678901234567890",
+    "TransactionID": "NLJ41HAAAA",
+    "ResultParameters": {
+      "ResultParameter": [
+        { "Key": "TransactionAmount", "Value": 100 },
+        { "Key": "TransactionReceipt", "Value": "NLJ41HAAAA" },
+        { "Key": "ReceiverPartyPublicName", "Value": "254712345678 - John Doe" },
+        { "Key": "TransactionDate", "Value": "25.1.2025 12:00:00 AM" }
       ]
     }
   }
 }
 ```
 
-### C2B (Customer to Business)
-
-Enable customers to make payments directly to your business account. Customers initiate payments from their phones, and your business receives notifications.
-
-**Register URLs:**
+---
 
-Register confirmation and validation URLs that Safaricom will call when customers make payments to your PayBill or Till Number. This is a one-time setup required before receiving C2B payments.
+### B2B
 
-**Using ENV variables:**
 ```ruby
-# Set ENV variables: confirmation_url
-result = MpesaStk::C2B.register_url({
-  "validation_url" => "https://your-app.com/validation", # optional
-  "response_type" => "Completed" # or "Cancelled"
-})
+MpesaStk::B2B.call(500, '600000', command_id: 'BusinessPayBill', account_reference: 'INV-001')
 ```
 
-**Using hash parameters:**
-```ruby
-result = MpesaStk::C2B.register_url({
-  "key" => "your_key",
-  "secret" => "your_secret",
-  "short_code" => "174379",
-  "confirmation_url" => "https://your-app.com/confirmation",
-  "validation_url" => "https://your-app.com/validation", # optional
-  "response_type" => "Completed" # or "Cancelled"
-})
+**Immediate response** (same shape as B2C):
+
+```json
+{
+  "ResponseCode": "0",
+  "ResponseDescription": "The service request is processed successfully.",
+  "OriginatorConversationID": "12345-67890-1",
+  "ConversationID": "AG_20240101_12345678901234567890"
+}
 ```
 
-**Simulate Payment (Sandbox only):**
+Final payment outcome arrives on `result_url` in the same `Result` wrapper format as B2C.
 
-Simulate a customer payment in the sandbox environment. This allows you to test your C2B integration without requiring actual customer payments. Only available in sandbox, not production.
+---
 
-**Using ENV variables:**
-```ruby
-# Set ENV variables: business_short_code
-result = MpesaStk::C2B.simulate("100", "254712345678", {
-  "command_id" => "CustomerPayBillOnline", # or "CustomerBuyGoodsOnline"
-  "bill_ref_number" => "INV001" # optional
-})
-```
+### C2B
 
-**Using hash parameters:**
 ```ruby
-result = MpesaStk::C2B.simulate("100", "254712345678", {
-  "key" => "your_key",
-  "secret" => "your_secret",
-  "short_code" => "174379",
-  "command_id" => "CustomerPayBillOnline", # or "CustomerBuyGoodsOnline"
-  "bill_ref_number" => "INV001" # optional
-})
+MpesaStk::C2B.register(validation_url: 'https://your.app/validate')
+MpesaStk::C2B.call(100, '254712345678', bill_ref_number: 'ORDER-1')
 ```
 
-**C2B Callbacks:**
-
-C2B payments use two types of callbacks:
-- **Validation URL**: Called when a payment is initiated (you can accept or reject)
-- **Confirmation URL** (`confirmation_url`): Called when payment is completed
+**Register URL — immediate response:**
 
-**Sample Validation Callback Payload:**
-```ruby
+```json
 {
-  "TransactionType" => "Pay Bill",
-  "TransID" => "LGR123456789",
-  "TransTime" => "20200101120000",
-  "TransAmount" => "100.00",
-  "BusinessShortCode" => "600000",
-  "BillRefNumber" => "Invoice123",
-  "InvoiceNumber" => "",
-  "OrgAccountBalance" => "50000.00",
-  "ThirdPartyTransID" => "",
-  "MSISDN" => "254712345678",
-  "FirstName" => "John",
-  "MiddleName" => "",
-  "LastName" => "Doe"
+  "ResponseCode": "0",
+  "ResponseDescription": "success"
 }
 ```
 
-**Sample Confirmation Callback Payload:**
-```ruby
+**Simulate — immediate response:**
+
+```json
 {
-  "TransactionType" => "Pay Bill",
-  "TransID" => "LGR123456789",
-  "TransTime" => "20200101120000",
-  "TransAmount" => "100.00",
-  "BusinessShortCode" => "600000",
-  "BillRefNumber" => "Invoice123",
-  "InvoiceNumber" => "",
-  "OrgAccountBalance" => "50000.00",
-  "ThirdPartyTransID" => "",
-  "MSISDN" => "254712345678",
-  "FirstName" => "John",
-  "MiddleName" => "",
-  "LastName" => "Doe"
+  "ResponseCode": "0",
+  "ResponseDescription": "Accept the service request successfully."
 }
 ```
 
-**Validation Response**: Your validation endpoint should return:
-```ruby
+**Confirmation callback** (Safaricom `POST` to `confirmation_url` on real payments):
+
+```json
 {
-  "ResultCode" => 0,  # 0 = Accept, C2B00011 = Reject
-  "ResultDesc" => "Accepted"
+  "TransactionType": "Pay Bill",
+  "TransID": "RKTQDM7W6S",
+  "TransTime": "20190608200106",
+  "TransAmount": "100.00",
+  "BusinessShortCode": "174379",
+  "BillRefNumber": "ORDER-1",
+  "InvoiceNumber": "",
+  "OrgAccountBalance": "49197.00",
+  "ThirdPartyTransID": "",
+  "MSISDN": "254712345678",
+  "FirstName": "John",
+  "MiddleName": "",
+  "LastName": "Doe"
 }
 ```
 
-### Account Balance
-
-Query the current balance of your business M-Pesa account (PayBill or Till Number). Returns the available balance and other account details. Results are sent asynchronously to your ResultURL.
+---
 
-**Using ENV variables:**
-```ruby
-# Set ENV variables: initiator, security_credential, result_url, queue_timeout_url
-result = MpesaStk::AccountBalance.query({})
-```
+### Transaction status
 
-**Using hash parameters:**
 ```ruby
-result = MpesaStk::AccountBalance.query({
-  "key" => "your_key",
-  "secret" => "your_secret",
-  "initiator" => "testapi",
-  "security_credential" => "encrypted_credential",
-  "party_a" => "174379", # optional, defaults to business_short_code
-  "result_url" => "https://your-app.com/result",
-  "queue_timeout_url" => "https://your-app.com/timeout"
-})
+MpesaStk::TransactionStatus.call('RKTQDM7W6S')
 ```
 
-**Account Balance Callbacks:**
+**Immediate response:**
 
-Account balance queries send results to `result_url` and `queue_timeout_url`.
-
-**Sample Result Callback Payload:**
-```ruby
+```json
 {
-  "Result" => {
-    "ResultType" => 0,
-    "ResultCode" => 0,
-    "ResultDesc" => "The service request is processed successfully.",
-    "OriginatorConversationID" => "12345-67890-1",
-    "ConversationID" => "AG_20200101_00001234567890",
-    "ResultParameters" => {
-      "ResultParameter" => [
-        {"Key" => "AccountBalance", "Value" => "Working Account|KES|50000.00|50000.00|0.00|0.00"},
-        {"Key" => "BOCompletedTime", "Value" => "20200101120000"}
-      ]
-    }
-  }
+  "ResponseCode": "0",
+  "ResponseDescription": "The service request is processed successfully.",
+  "ConversationID": "AG_20240101_12345678901234567890",
+  "OriginatorConversationID": "12345-67890-1"
 }
 ```
 
-### Reversal
+**Result callback** (`result_url`) includes transaction details inside `Result.ResultParameters` (same pattern as B2C).
 
-Reverse a previously completed M-Pesa transaction. Useful for refunds, correcting errors, or handling disputes. The reversal amount must match the original transaction amount. Results are sent asynchronously to your ResultURL.
+---
 
-**Using ENV variables:**
-```ruby
-# Set ENV variables: initiator, security_credential, result_url, queue_timeout_url
-result = MpesaStk::Reversal.reverse("OFR4Z5EE9Y", "100", {})
-```
+### Account balance
 
-**Using hash parameters:**
 ```ruby
-result = MpesaStk::Reversal.reverse("OFR4Z5EE9Y", "100", {
-  "key" => "your_key",
-  "secret" => "your_secret",
-  "initiator" => "testapi",
-  "security_credential" => "encrypted_credential",
-  "receiver_party" => "174379", # optional, defaults to business_short_code
-  "receiver_identifier_type" => "4", # optional, defaults to "4"
-  "result_url" => "https://your-app.com/result",
-  "queue_timeout_url" => "https://your-app.com/timeout"
-})
+MpesaStk::AccountBalance.call
 ```
 
-**Reversal Callbacks:**
+**Immediate response:**
+
+```json
+{
+  "ResponseCode": "0",
+  "ResponseDescription": "The service request is processed successfully.",
+  "OriginatorConversationID": "12345-67890-1",
+  "ConversationID": "AG_20240101_12345678901234567890"
+}
+```
 
-Reversal requests send results to `result_url` and `queue_timeout_url`.
+**Result callback** (`result_url`) — balance in `ResultParameters`:
 
-**Sample Result Callback Payload:**
-```ruby
+```json
 {
-  "Result" => {
-    "ResultType" => 0,
-    "ResultCode" => 0,
-    "ResultDesc" => "The service request is processed successfully.",
-    "OriginatorConversationID" => "12345-67890-1",
-    "ConversationID" => "AG_20200101_00001234567890",
-    "TransactionID" => "LGR123456789",
-    "ResultParameters" => {
-      "ResultParameter" => [
-        {"Key" => "TransactionAmount", "Value" => "100.00"},
-        {"Key" => "TransactionReceipt", "Value" => "LGR123456789"},
-        {"Key" => "B2CWorkingAccountAvailableFunds", "Value" => "50000.00"},
-        {"Key" => "B2CUtilityAccountAvailableFunds", "Value" => "100000.00"},
-        {"Key" => "TransactionCompletedDateTime", "Value" => "01.01.2020 12:00:00"}
+  "Result": {
+    "ResultType": 0,
+    "ResultCode": 0,
+    "ResultDesc": "The service request is processed successfully.",
+    "OriginatorConversationID": "12345-67890-1",
+    "ConversationID": "AG_20240101_12345678901234567890",
+    "ResultParameters": {
+      "ResultParameter": [
+        { "Key": "AccountBalance", "Value": "3080.00" },
+        { "Key": "BOCompletedTime", "Value": "20250125120000" }
       ]
     }
   }
 }
 ```
 
-### M-Pesa Ratiba (Standing Orders)
-
-Create standing orders (recurring payments) that automatically charge customers at specified intervals. Perfect for subscriptions, monthly fees, or any recurring billing. Customers authorize the standing order once, and payments are automatically processed according to the frequency you set (daily, weekly, monthly, etc.).
+---
 
-**Using ENV variables:**
-```ruby
-# Set ENV variables: business_short_code, callback_url
-# Monthly subscription (Pay Bill)
-result = MpesaStk::Ratiba.create_standing_order({
-  "standing_order_name" => "Monthly Subscription",
-  "amount" => "500",
-  "party_a" => "254712345678",
-  "frequency" => "3", # 1=Daily, 2=Weekly, 3=Monthly, 4=Bi-Monthly, 5=Quarterly, 6=Half-Year, 7=Yearly
-  "start_date" => "2025-09-25",
-  "end_date" => "2026-09-25",
-  "account_reference" => "SUB001",
-  "transaction_desc" => "Monthly subscription payment"
-})
-
-# For Buy Goods (Till Number)
-result = MpesaStk::Ratiba.create_standing_order({
-  "amount" => "500",
-  "party_a" => "254712345678",
-  "transaction_type" => "Standing Order Customer Pay Merchant",
-  "receiver_party_identifier_type" => "2", # "2" for till number
-  "frequency" => "3",
-  "start_date" => "2025-09-25",
-  "end_date" => "2026-09-25"
-})
-```
+### Reversal
 
-**Using hash parameters:**
 ```ruby
-# Monthly subscription (Pay Bill)
-result = MpesaStk::Ratiba.create_standing_order({
-  "key" => "your_key",
-  "secret" => "your_secret",
-  "business_short_code" => "174379",
-  "standing_order_name" => "Monthly Subscription",
-  "amount" => "500",
-  "party_a" => "254712345678",
-  "frequency" => "3",
-  "start_date" => "2025-09-25",
-  "end_date" => "2026-09-25",
-  "account_reference" => "SUB001",
-  "transaction_desc" => "Monthly subscription payment",
-  "callback_url" => "https://your-app.com/callback"
-})
-
-# For Buy Goods (Till Number)
-result = MpesaStk::Ratiba.create_standing_order({
-  "key" => "your_key",
-  "secret" => "your_secret",
-  "business_short_code" => "300584",
-  "amount" => "500",
-  "party_a" => "254712345678",
-  "transaction_type" => "Standing Order Customer Pay Merchant",
-  "receiver_party_identifier_type" => "2",
-  "frequency" => "3",
-  "start_date" => "2025-09-25",
-  "end_date" => "2026-09-25",
-  "callback_url" => "https://your-app.com/callback"
-})
+MpesaStk::Reversal.call('RKTQDM7W6S', 100)
 ```
 
-**Note:** Ratiba (Standing Orders) uses the same callback structure as STK Push. When a standing order payment is processed, you'll receive a callback on your `callback_url` with the transaction status.
-
-### IoT APIs
-
-Manage IoT SIM cards and send/receive messages for IoT devices. These APIs allow you to monitor, activate, and manage SIM cards used in IoT deployments, as well as send and receive SMS messages from IoT devices.
-
-**SIM Operations:**
-
-Manage and query information about IoT SIM cards including activation status, lifecycle, customer information, location, and subscription management.
-
-**Using ENV variables:**
-```ruby
-# Set ENV variables: iot_api_key, vpn_group, username
-iot = MpesaStk::IoT.sims({})
+**Immediate response:**
 
-# Get all SIMs
-result = iot.get_all_sims(start_at_index: 0, page_size: 10)
-
-# Query lifecycle status
-result = iot.query_lifecycle_status("0110100606")
-
-# Query customer info
-result = iot.query_customer_info("0110100606")
-
-# Activate SIM
-result = iot.sim_activation("0110100606")
-
-# Get activation trends
-result = iot.get_activation_trends(start_date: "2025-01-01", stop_date: "2025-12-31")
-
-# Rename asset
-result = iot.rename_asset("0110100606", "New Asset Name")
-
-# Get location info
-result = iot.get_location_info("0110100606")
-
-# Suspend/Unsuspend subscription
-result = iot.suspend_unsuspend_sub("0110100606", "product_name", "suspend") # or "unsuspend"
+```json
+{
+  "ResponseCode": "0",
+  "ResponseDescription": "The service request is processed successfully.",
+  "OriginatorConversationID": "12345-67890-1",
+  "ConversationID": "AG_20240101_12345678901234567890"
+}
 ```
 
-**Using hash parameters:**
-```ruby
-iot = MpesaStk::IoT.sims({
-  "key" => "your_key",
-  "secret" => "your_secret",
-  "iot_api_key" => "Yl4S3KEcr173mbeUdYdjf147IuG3rJ824ArMkP6Z",
-  "vpn_group" => "your_vpn_group",
-  "username" => "your_username"
-})
-
-# All operations work the same way
-result = iot.get_all_sims(start_at_index: 0, page_size: 10)
-result = iot.query_lifecycle_status("0110100606")
-# ... etc
-```
+Outcome is confirmed on `result_url` via the standard `Result` object.
 
-**Messaging Operations:**
+---
 
-Send and manage SMS messages to/from IoT devices. Includes functionality to send messages, search message history, filter messages by date/status, and manage message threads.
+### Ratiba (standing orders)
 
-**Using ENV variables:**
 ```ruby
-# Set ENV variables: iot_api_key, vpn_group, username
-messaging = MpesaStk::IoT.messaging({})
-
-# Get all messages
-result = messaging.get_all_messages(page_no: 1, page_size: 10)
-
-# Search messages
-result = messaging.search_messages("search_term", page_no: 1, page_size: 5)
-
-# Filter messages
-result = messaging.filter_messages(
-  start_date: "2025-01-01",
-  end_date: "2025-12-31",
-  status: "sent", # optional
-  page_no: 1,
-  page_size: 10
+MpesaStk::Ratiba.call(
+  amount: 100,
+  party_a: '254712345678',
+  start_date: '2025-01-01',
+  end_date: '2025-12-31',
+  frequency: '3',
+  account_reference: 'SUB-001'
 )
-
-# Send single message
-result = messaging.send_single_message("0110100606", "Hello from API")
-
-# Delete message
-result = messaging.delete_message(123)
-
-# Delete message thread
-result = messaging.delete_message_thread("0110100606")
 ```
 
-**Using hash parameters:**
-```ruby
-messaging = MpesaStk::IoT.messaging({
-  "key" => "your_key",
-  "secret" => "your_secret",
-  "iot_api_key" => "Yl4S3KEcr173mbeUdYdjf147IuG3rJ824ArMkP6Z",
-  "vpn_group" => "your_vpn_group",
-  "username" => "your_username"
-})
-
-# All operations work the same way
-result = messaging.get_all_messages(page_no: 1, page_size: 10)
-result = messaging.send_single_message("0110100606", "Hello from API")
-# ... etc
-```
+**Immediate response:**
 
-### IMSI/SWAP Operations
+```json
+{
+  "ResponseCode": "0",
+  "ResponseDescription": "The service request is processed successfully.",
+  "OriginatorConversationID": "12345-67890-1",
+  "ConversationID": "AG_20240101_12345678901234567890"
+}
+```
 
-Query International Mobile Subscriber Identity (IMSI) and SIM Swap information for a phone number. Useful for fraud prevention, verifying SIM card authenticity, and checking if a SIM card has been swapped recently. Available in both v1 and v2 API versions.
+Standing-order charge results are delivered to `callback_url` per Daraja Ratiba documentation.
 
-**Using ENV variables:**
-```ruby
-# Check ATI (v1)
-result = MpesaStk::IMSI.check_ati("254712345678", {})
+---
 
-# Check ATI (v2)
-result = MpesaStk::IMSI.check_ati("254712345678", {}, version: "v2")
-```
+### Pull transactions
 
-**Using hash parameters:**
 ```ruby
-# Check ATI (v1)
-result = MpesaStk::IMSI.check_ati("254712345678", {
-  "key" => "your_key",
-  "secret" => "your_secret"
-})
-
-# Check ATI (v2)
-result = MpesaStk::IMSI.check_ati("254712345678", {
-  "key" => "your_key",
-  "secret" => "your_secret"
-}, version: "v2")
+MpesaStk::PullTransactions.register(request_type: 'Pull', nominated_number: '254712345678')
+MpesaStk::PullTransactions.call('2025-01-01 00:00:00', '2025-01-31 23:59:59')
 ```
 
-### Pull Transactions
+**Register — immediate response:**
 
-Retrieve historical transaction data from your PayBill or Till Number. This API allows you to pull transaction records for reconciliation, reporting, or analysis purposes.
+```json
+{
+  "ResponseCode": "0",
+  "ResponseDescription": "success"
+}
+```
 
-**Register Pull URL:**
+**Query — immediate response**
 
-Register a callback URL where Safaricom will send transaction data when you query for transactions. This is a one-time setup required before querying transactions.
+The gem returns whatever JSON Safaricom sends (`JSON.parse` only). The repo does **not** include a captured production/sandbox payload for this endpoint. Tests stub a minimal shape:
 
-**Using ENV variables:**
-```ruby
-# Set ENV variables: callback_url
-result = MpesaStk::PullTransactions.register({
-  "request_type" => "pull",
-  "nominated_number" => "254712345678"
-})
+```json
+{
+  "ResponseCode": "0",
+  "data": []
+}
 ```
 
-**Using hash parameters:**
-```ruby
-result = MpesaStk::PullTransactions.register({
-  "key" => "your_key",
-  "secret" => "your_secret",
-  "short_code" => "174379",
-  "request_type" => "pull",
-  "nominated_number" => "254712345678",
-  "callback_url" => "https://your-app.com/pull_callback"
-})
-```
+Here `data: []` is a **placeholder** in tests meaning “success, list field exists”—not “the API never returns rows.” When transactions exist for the date range, expect objects inside `data` (field names per [Daraja pull-transactions docs](https://developer.safaricom.co.ke/)). Historical rows may also arrive on your registered `callback_url`.
 
-**Query Transactions:**
+---
 
-Query and retrieve transaction records for a specific date range. Returns transaction details including amounts, phone numbers, transaction IDs, and timestamps. Results are sent asynchronously to your registered callback URL.
+### IMSI / SIM swap
 
-**Using ENV variables:**
 ```ruby
-# Set ENV variables: business_short_code
-result = MpesaStk::PullTransactions.query(
-  "2020-08-04 8:36:00",
-  "2020-08-16 10:10:00",
-  {
-    "offset_value" => "0" # optional
-  }
-)
+MpesaStk::IMSI.call('254712345678', version: 'v2')
 ```
 
-**Using hash parameters:**
-```ruby
-result = MpesaStk::PullTransactions.query(
-  "2020-08-04 8:36:00",
-  "2020-08-16 10:10:00",
-  {
-    "key" => "your_key",
-    "secret" => "your_secret",
-    "short_code" => "174379",
-    "offset_value" => "0" # optional
-  }
-)
-```
+**Immediate response**
 
-**Pull Transactions Callbacks:**
+Same as above: the gem passes through the API body. Tests stub `{ "success": true, "data": {} }`—`data: {}` is a **placeholder**, not documentation of an empty real response. Live `checkATI` payloads (v1/v2) include swap/IMSI fields inside `data` per Safaricom’s spec. Use this to gate high-risk flows (e.g. extra verification after a recent SIM swap).
 
-Pull transaction queries send results to the registered `callback_url`.
+---
 
-**Sample Callback Payload:**
-```ruby
-{
-  "Result" => {
-    "ResultType" => 0,
-    "ResultCode" => 0,
-    "ResultDesc" => "The service request is processed successfully.",
-    "OriginatorConversationID" => "12345-67890-1",
-    "ConversationID" => "AG_20200101_00001234567890",
-    "ResultParameters" => {
-      "ResultParameter" => [
-        {
-          "Key" => "TransactionDetails",
-          "Value" => "TransactionID|TransactionTime|Amount|MSISDN|FirstName|MiddleName|LastName|BusinessShortCode|BillRefNumber|InvoiceNumber|ThirdPartyTransID|TransactionStatus|TransactionType|OrgAccountBalance"
-        }
-      ]
-    }
-  }
-}
-```
+### IoT SIM portal
 
-## Handling Callbacks in Your Application
+Shortcuts:
 
-**Rails Example:**
 ```ruby
-# config/routes.rb
-post '/mpesa/callback', to: 'mpesa#stk_callback'
-post '/mpesa/result', to: 'mpesa#result_callback'
-post '/mpesa/timeout', to: 'mpesa#timeout_callback'
-post '/mpesa/confirmation', to: 'mpesa#c2b_confirmation'
-
-# app/controllers/mpesa_controller.rb
-class MpesaController < ApplicationController
-  skip_before_action :verify_authenticity_token, only: [:stk_callback, :result_callback, :timeout_callback, :c2b_confirmation]
-
-  def stk_callback
-    callback_data = JSON.parse(request.body.read)
-    result_code = callback_data.dig('Body', 'stkCallback', 'ResultCode')
-    
-    if result_code == 0
-      # Transaction successful
-      metadata = callback_data.dig('Body', 'stkCallback', 'CallbackMetadata', 'Item')
-      amount = metadata.find { |item| item['Name'] == 'Amount' }['Value']
-      receipt = metadata.find { |item| item['Name'] == 'MpesaReceiptNumber' }['Value']
-      # Process successful payment
-    else
-      # Transaction failed
-      result_desc = callback_data.dig('Body', 'stkCallback', 'ResultDesc')
-      # Handle failure
-    end
-    
-    render json: { status: 'received' }, status: :ok
-  end
-
-  def result_callback
-    result_data = JSON.parse(request.body.read)
-    result_code = result_data.dig('Result', 'ResultCode')
-    
-    if result_code == 0
-      # Process successful result
-    else
-      # Handle error
-    end
-    
-    render json: { status: 'received' }, status: :ok
-  end
-
-  def timeout_callback
-    timeout_data = JSON.parse(request.body.read)
-    # Handle timeout
-    render json: { status: 'received' }, status: :ok
-  end
-
-  def c2b_confirmation
-    confirmation_data = JSON.parse(request.body.read)
-    trans_id = confirmation_data['TransID']
-    amount = confirmation_data['TransAmount']
-    # Process C2B payment confirmation
-    render json: { status: 'received' }, status: :ok
-  end
-end
+MpesaStk::IoT.list_sims(start_at_index: 0, page_size: 10)
+MpesaStk::IoT.send_message('0110100606', 'Hello device')
 ```
 
-**Sinatra Example:**
+Or dispatch any instance method by name:
+
 ```ruby
-require 'sinatra'
-require 'json'
-
-post '/mpesa/callback' do
-  callback_data = JSON.parse(request.body.read)
-  # Process callback
-  status 200
-  { status: 'received' }.to_json
-end
+MpesaStk::IoT.call(:query_lifecycle_status, '0110100606')
+MpesaStk::IoT.call(:search_messages, 'keyword', page_no: 1, page_size: 5)
 ```
 
-**Best Practices:**
-
-1. **Always Return 200 OK**: Your callback endpoint must return HTTP 200 OK within 30 seconds
-2. **Idempotency**: Use `TransactionID` or `CheckoutRequestID` to prevent duplicate processing
-3. **Logging**: Log all callbacks for debugging and audit purposes
-4. **Error Handling**: Handle network issues and retries gracefully
-5. **Security**: Validate callback authenticity (consider IP whitelisting or signature verification)
-6. **Queue Processing**: Use background jobs for processing callbacks to avoid timeouts
-
-## Response Format & Error Handling
+**List SIMs / messages**
 
-### Success Response Format
+Tests stub a minimal success body (again, **not** a guarantee of empty inventory):
 
-All API methods return a hash with the response. Success responses typically include:
-- `ResponseCode`: "0" indicates success
-- `ResponseDescription`: Human-readable description
-- `MerchantRequestID` / `OriginatorConversationID`: Request identifiers
-- `CheckoutRequestID` / `ConversationID`: Transaction identifiers
-
-**Example Success Response:**
-```ruby
+```json
 {
-  "MerchantRequestID" => "7909-1302368-1",
-  "CheckoutRequestID" => "ws_CO_DMZ_40472724_16062018092359957",
-  "ResponseCode" => "0",
-  "ResponseDescription" => "Success. Request accepted for processing",
-  "CustomerMessage" => "Success. Request accepted for processing"
+  "success": true,
+  "data": []
 }
 ```
 
-### Error Response Format
+With SIMs or messages present, `data` is typically an **array of objects** (MSISDN, status, pagination fields, etc.—per endpoint). Capture one response from your sandbox account and treat that as your reference.
 
-Error responses include:
-- `errorCode`: Error code (e.g., "500.001.1001")
-- `errorMessage`: Error description
-- `requestId`: Request identifier
+**Send message** — tests only assert success; a plausible live shape might look like:
 
-**Example Error Response:**
-```ruby
+```json
 {
-  "requestId" => "13022-8633727-1",
-  "errorCode" => "500.001.1001",
-  "errorMessage" => "Error Message"
+  "success": true,
+  "data": {
+    "messageId": "msg-12345",
+    "status": "sent"
+  }
 }
 ```
 
-### Error Handling
+That send-message example is **illustrative**; confirm against the IoT portal API docs for your environment.
 
-All methods raise `StandardError` with descriptive messages when:
-- HTTP requests fail
-- Required configuration is missing
-- API returns error responses
+Other IoT methods include `query_lifecycle_status`, `sim_activation`, `get_all_messages`, `filter_messages`, `delete_message`, and `delete_message_thread`. Responses come directly from the portal API and vary by endpoint.
 
-```ruby
-begin
-  result = MpesaStk::PushPayment.call("500", "254712345678")
-rescue StandardError => e
-  puts "Error: #{e.message}"
-end
-```
+---
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run the tests:
-
 ```bash
-# Run all tests
-ruby -Itest test/*_test.rb
-
-# Or run specific test file
-ruby -Itest test/access_token_test.rb
+git clone https://github.com/mboya/mpesa_stk.git
+cd mpesa_stk
+bin/setup          # bundle install
+cp .sample.env .env
+bundle exec rake test
+bundle exec rubocop
 ```
 
-You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-**Note:** If you encounter bundler deprecation warnings, update bundler with `gem install bundler` (requires bundler 2.4+ for Ruby 3.3+).
+Use the [Safaricom sandbox](https://developer.safaricom.co.ke/) and valid test credentials in `.env` for manual checks.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```bash
+bundle exec rake test   # 75 tests, WebMock (no live API calls)
+bundle exec rubocop
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/mboya/mpesa_stk.
+1. Fork the repository and create a feature branch.
+2. Add tests for new behaviour under `test/`.
+3. Run `bundle exec rake test` and `bundle exec rubocop`.
+4. Open a pull request with a clear description.
 
-To Contribute to this gem,
-* Comment on the issue you would like to work on solving.
-* Mark the issue as in progress by adding an `in-progress` label.
-* Fork the project to your github repository (This project only accepts PRs from forks)
-* Submit the PR after the implementation all unfinished PRs for an issue should have a WIP indicated beside it
-* Every PR should have a link to the issue being solved
-* Checkout this [github best practices](https://github.com/skyscreamer/yoga/wiki/GitHub-Best-Practices) for more info.
+Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before participating. Security issues: see [SECURITY.md](SECURITY.md). Release history: [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the MpesaStk project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/mboya/mpesa_stk/blob/master/CODE_OF_CONDUCT.md).
-
+Copyright (c) 2018 mboya. Released under the [MIT License](LICENSE.txt).