paytree 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10a40048e820db73f15da4bdc6511d33883870c4dd31fa6ed97fdffab5078171
-  data.tar.gz: 6325d61fc365dc3a7264f3564af03aead8da63aaec305f3604b58dba20d0094a
+  metadata.gz: db5f3b07684338b0a9b63dabf3cc2a00d01adbfcb0c5e8511dd734fc3071d0e7
+  data.tar.gz: aa49b4d56b4eba825fa81ef7a5ff9c75708b92b6036ee5e6439fc1b0821a5e15
 SHA512:
-  metadata.gz: 2d953e2487d35dbcd709d174fbf2f03c1199a9cefbdfe913d0209f093840a16ac3ae8ba9d3a4ef401f2480657c9cb1858a400ae08db9494807e1420a88939cdc
-  data.tar.gz: a50c13a82b78bfd06726ad4b8acd1759e0e196a0eb7e28b4fbc618683f3dde4dae0142ec848237992d23ba8532ff1ffaa3f65d9662e39ef95fb5c01a97afa140
+  metadata.gz: d56d06d79d80c8a26569cc9c51b3b55eee3b3ec376e69f40ea21a6e37e325e57a2877cf344be727a98b79614b594ca33feffbadc2591e37f3a5f3d3d5d1d788e
+  data.tar.gz: d8dade7c6661f6ef505c5b25dbbacbbc744610f2333f9ba8d433bcbc01beea82b694abc7727c9c7a8ecf2d1eccd81e5c69caad380930fc162d3c49ad8f6730b0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    paytree (0.2.0)
+    paytree (0.3.0)
       faraday (~> 2.0)
 
 GEM
@@ -148,6 +148,7 @@ GEM
 
 PLATFORMS
   x86_64-darwin-24
+  x86_64-darwin-25
   x86_64-linux
 
 DEPENDENCIES

data/README.md

@@ -1,6 +1,16 @@
+<p align="center">
+  <img src="https://badge.fury.io/rb/paytree.svg" />
+  <img src="https://img.shields.io/badge/license-MIT-green.svg" />
+  <img src="https://img.shields.io/badge/ruby-3.2+-red" />
+  <a href="https://github.com/mundanecodes/paytree/actions">
+    <img src="https://github.com/mundanecodes/paytree/actions/workflows/ci.yml/badge.svg" />
+  </a>
+</p>
+
 # Paytree
 
-A simple, highly opinionated Rails-optional Ruby gem for mobile money integrations. Currently supports Kenya's M-Pesa via the Daraja API with plans for additional providers.
+A simple, highly opinionated Rails-optional Ruby gem for mobile money integrations.
+Currently supports Kenya's M-Pesa via the Daraja API with plans for additional providers.
 
 ## Features
 
@@ -8,6 +18,8 @@ A simple, highly opinionated Rails-optional Ruby gem for mobile money integratio
 - **Convention over Configuration**: One clear setup pattern, opinionated defaults
 - **Safe Defaults**: Sandbox mode, proper timeouts, comprehensive error handling
 - **Batteries Included**: STK Push, B2C, B2B, C2B operations out of the box
+- **API Versioning**: Support for both Daraja API v1 and v3 with backward compatibility
+- **Enhanced Reliability**: Automatic token retry with exponential backoff
 - **Security First**: Credential management, no hardcoded secrets
 
 ## Quick Start
@@ -79,12 +91,59 @@ Paytree.configure_mpesa(
 #   shortcode: "YOUR_PRODUCTION_SHORTCODE",
 #   passkey: Rails.application.credentials.mpesa[:passkey],
 #   sandbox: false,
-#   retryable_errors: ["429.001.01", "500.001.02", "503.001.01"]  # Optional: errors to retry
+#   api_version: "v1",                                            # Optional: "v1" (default) or "v3"
+#   retryable_errors: ["429.001.01", "500.001.02", "503.001.01"] # Optional: errors to retry
 # )
 ```
 
 ---
 
+## API Version Support
+
+Paytree supports both M-Pesa Daraja API v1 and v3 endpoints. The API version can be configured globally or via environment variables.
+
+### Configuration Options
+
+```ruby
+# Use v1 API (default - backward compatible)
+Paytree.configure_mpesa(
+  key: "YOUR_KEY",
+  secret: "YOUR_SECRET",
+  api_version: "v1"  # Default
+)
+
+# Use v3 API (latest features)
+Paytree.configure_mpesa(
+  key: "YOUR_KEY",
+  secret: "YOUR_SECRET",
+  api_version: "v3"
+)
+
+# Or via environment variable
+ENV['MPESA_API_VERSION'] = 'v3'
+Paytree.configure_mpesa(
+  key: "YOUR_KEY",
+  secret: "YOUR_SECRET"
+  # api_version automatically picked up from ENV
+)
+```
+
+### Differences Between v1 and v3
+
+| Feature | v1 | v3 |
+|---------|----|----|
+| **Endpoints** | `/mpesa/b2c/v1/paymentrequest` | `/mpesa/b2c/v3/paymentrequest` |
+| **OriginatorConversationID** | Not required | Auto-generated UUID |
+| **Reliability** | Standard | Enhanced with better tracking |
+
+
+**Backward Compatibility:**
+- Existing code continues to work unchanged (defaults to v1)
+- No breaking changes when upgrading Paytree versions
+- Can switch between v1/v3 by changing configuration only
+
+---
+
 ## Usage Examples
 
 ### STK Push (Customer Payment)
@@ -158,7 +217,7 @@ end
 
 Send funds directly to a customer’s M-Pesa wallet via the B2C API.
 
-### Example
+### Basic Example
 ```ruby
 response = Paytree::Mpesa::B2C.call(
   phone_number: "254712345678",
@@ -176,6 +235,43 @@ else
 end
 ```
 
+### v3 API Features
+
+When using `api_version: "v3"`, B2C calls automatically include an `OriginatorConversationID` for enhanced tracking:
+
+```ruby
+# Configure for v3 API
+Paytree.configure_mpesa(
+  key: "YOUR_KEY",
+  secret: "YOUR_SECRET",
+  api_version: "v3"
+)
+
+# Same call, but now uses v3 endpoint with auto-generated OriginatorConversationID
+response = Paytree::Mpesa::B2C.call(
+  phone_number: "254712345678",
+  amount: 100
+)
+
+# v3 response includes additional tracking data
+if response.success?
+  puts "Conversation ID: #{response.data["ConversationID"]}"
+  puts "Originator ID: #{response.data["OriginatorConversationID"]}" # Auto-generated UUID
+end
+```
+
+### Custom OriginatorConversationID (v3 only)
+
+You can provide your own tracking ID for v3 API calls:
+
+```ruby
+response = Paytree::Mpesa::B2C.call(
+  phone_number: "254712345678",
+  amount: 100,
+  originator_conversation_id: "CUSTOM-TRACK-#{Time.now.to_i}"
+)
+```
+
 ---
 
 ## C2B (Customer to Business)
@@ -268,10 +364,10 @@ unless response.success?
   puts response.code     # "404.001.03" (if available)
   puts response.data     # {
                          #   "requestId" => "",
-                         #   "errorCode" => "404.001.03", 
+                         #   "errorCode" => "404.001.03",
                          #   "errorMessage" => "Invalid Access Token"
                          # }
-  
+
   # Check if error is retryable (based on configuration)
   if response.retryable?
     puts "This error can be retried"
@@ -311,6 +407,9 @@ Paytree allows you to configure which error codes should be considered retryable
 - `"429.001.01"` - Rate limit exceeded
 - `"500.001.02"` - Temporary server error
 - `"503.001.01"` - Service temporarily unavailable
+- `"timeout.connection"` - Network connection timeout (Net::OpenTimeout)
+- `"timeout.read"` - Network read timeout (Net::ReadTimeout)
+- `"timeout.request"` - HTTP request timeout (Faraday::TimeoutError)
 
 Configure retryable errors during setup:
 
@@ -318,7 +417,14 @@ Configure retryable errors during setup:
 Paytree.configure_mpesa(
   key: "YOUR_KEY",
   secret: "YOUR_SECRET",
-  retryable_errors: ["429.001.01", "500.001.02", "503.001.01"]
+  retryable_errors: [
+    "429.001.01",         # Rate limit
+    "500.001.02",         # Server error  
+    "503.001.01",         # Service unavailable
+    "timeout.connection", # Connection timeout
+    "timeout.read",       # Read timeout
+    "timeout.request"     # Request timeout
+  ]
 )
 ```
 

data/lib/paytree/configs/mpesa.rb

@@ -5,7 +5,7 @@ module Paytree
     class Mpesa
       attr_accessor :key, :secret, :shortcode, :passkey, :adapter,
         :initiator_name, :initiator_password, :sandbox,
-        :extras, :timeout, :retryable_errors
+        :extras, :timeout, :retryable_errors, :api_version
 
       def initialize
         @extras = {}
@@ -13,6 +13,7 @@ module Paytree
         @mutex = Mutex.new
         @timeout = 30      # Default 30 second timeout
         @retryable_errors = []  # Default empty array
+        @api_version = "v1"     # Default to v1 for backward compatibility
       end
 
       def base_url

data/lib/paytree/mpesa/adapters/daraja/b2b.rb

@@ -5,7 +5,9 @@ module Paytree
     module Adapters
       module Daraja
         class B2B < Base
-          ENDPOINT = "/mpesa/b2b/v1/paymentrequest"
+          def self.endpoint
+            "/mpesa/b2b/#{config.api_version}/paymentrequest"
+          end
 
           class << self
             def call(short_code:, receiver_shortcode:, amount:, account_reference:, **opts)
@@ -28,7 +30,7 @@ module Paytree
                   ResultURL: config.extras[:result_url]
                 }.compact
 
-                post_to_mpesa(:b2b, ENDPOINT, payload)
+                post_to_mpesa(:b2b, endpoint, payload)
               end
             end
           end

data/lib/paytree/mpesa/adapters/daraja/b2c.rb

@@ -5,7 +5,9 @@ module Paytree
     module Adapters
       module Daraja
         class B2C < Base
-          ENDPOINT = "/mpesa/b2c/v1/paymentrequest"
+          def self.endpoint
+            "/mpesa/b2c/#{config.api_version}/paymentrequest"
+          end
 
           class << self
             def call(phone_number:, amount:, **opts)
@@ -23,9 +25,14 @@ module Paytree
                   CommandID: opts[:command_id] || "BusinessPayment",
                   Remarks: opts[:remarks] || "OK",
                   Occasion: opts[:occasion] || "Payment"
-                }.compact
+                }
+
+                # Add OriginatorConversationID for v3
+                if config.api_version == "v3"
+                  payload[:OriginatorConversationID] = opts[:originator_conversation_id] || generate_conversation_id
+                end
 
-                post_to_mpesa(:b2c, ENDPOINT, payload)
+                post_to_mpesa(:b2c, endpoint, payload.compact)
               end
             end
           end

data/lib/paytree/mpesa/adapters/daraja/base.rb

@@ -1,4 +1,5 @@
 require "base64"
+require "securerandom"
 require_relative "response_helpers"
 require_relative "../../../utils/error_handling"
 
@@ -106,6 +107,10 @@ module Paytree
               end
             end
 
+            def generate_conversation_id
+              SecureRandom.uuid
+            end
+
             private
 
             def fetch_token

data/lib/paytree/utils/error_handling.rb

@@ -7,7 +7,7 @@ module Paytree
         Paytree::Errors::Base => e
         emit_error(e, context)
         raise
-      rescue Faraday::TimeoutError => e
+      rescue Faraday::TimeoutError, Net::OpenTimeout, Net::ReadTimeout => e
         handle_faraday_error(
           e,
           context,
@@ -54,7 +54,11 @@ module Paytree
           code = info[:code]
         else
           message = error.message
-          code = nil
+          code = case error
+          when Net::OpenTimeout then "timeout.connection"
+          when Net::ReadTimeout then "timeout.read"
+          when Faraday::TimeoutError then "timeout.request"
+          end
         end
 
         wrap_and_raise(

data/lib/paytree/version.rb

@@ -1,3 +1,3 @@
 module Paytree
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/paytree.rb

@@ -51,7 +51,8 @@ module Paytree
         passkey: "MPESA_PASSKEY",
         initiator_name: "MPESA_INITIATOR_NAME",
         initiator_password: "MPESA_INITIATOR_PASSWORD",
-        sandbox: "MPESA_SANDBOX"
+        sandbox: "MPESA_SANDBOX",
+        api_version: "MPESA_API_VERSION"
       }
 
       config = {}

data/paytree.gemspec

@@ -6,8 +6,10 @@ Gem::Specification.new do |spec|
   spec.authors = ["Charles Chuck"]
   spec.email = ["chalcchuck@gmail.com"]
 
-  spec.summary = "Rails-optional payments abstraction for M-Pesa (Daraja) and more."
-  spec.description = "Clean, adapter-based Ruby DSL for mobile money integrations like M-Pesa via Daraja, with future provider support (Tingg, Airtel, Cellulant)."
+  spec.summary = "A Ruby wrapper for the Mpesa API in Kenya."
+  spec.description = <<~DESC
+    Paytree is a lightweight Ruby wrapper for the full Mpesa API suite in Kenya - including B2C, C2B, STK Push and more. It supports certificate encryption, clean facades, and a pluggable adapter system (e.g. Daraja, Airtel..). Built for Rails and pure Ruby apps.
+  DESC
   spec.homepage = "https://github.com/mundanecodes/paytree"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.2.0"
@@ -20,10 +22,12 @@ Gem::Specification.new do |spec|
   spec.metadata["wiki_uri"] = "https://github.com/mundanecodes/paytree/wiki"
   spec.metadata["mailing_list_uri"] = "https://github.com/mundanecodes/paytree/discussions"
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["keywords"] = "mpesa,mpesa-api,b2c,stk-push,mobile-money,payments,daraja"
+  spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
-      f.match(%r{^(test|spec|features|bin|exe)/}) || f.include?(".git")
+      f.match(%r{^(test|spec|features|bin|exe)/}) || f.include?(".git") || f.end_with?(".gem")
     end
   end
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: paytree
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Charles Chuck
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-20 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -80,8 +79,12 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Clean, adapter-based Ruby DSL for mobile money integrations like M-Pesa
-  via Daraja, with future provider support (Tingg, Airtel, Cellulant).
+description: 'Paytree is a lightweight Ruby wrapper for the full Mpesa API suite in
+  Kenya - including B2C, C2B, STK Push and more. It supports certificate encryption,
+  clean facades, and a pluggable adapter system (e.g. Daraja, Airtel..). Built for
+  Rails and pure Ruby apps.
+
+  '
 email:
 - chalcchuck@gmail.com
 executables: []
@@ -134,7 +137,8 @@ metadata:
   wiki_uri: https://github.com/mundanecodes/paytree/wiki
   mailing_list_uri: https://github.com/mundanecodes/paytree/discussions
   allowed_push_host: https://rubygems.org
-post_install_message:
+  keywords: mpesa,mpesa-api,b2c,stk-push,mobile-money,payments,daraja
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -149,8 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
-summary: Rails-optional payments abstraction for M-Pesa (Daraja) and more.
+summary: A Ruby wrapper for the Mpesa API in Kenya.
 test_files: []