paytree 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03f7bf934f81e5f84019e8e2a20026e49db6f363433e7c00ce5b6d6ddbf6d177
-  data.tar.gz: 6698c7711565529fcd2397120d40fad539e2df905832549f06a8b565f0576a85
+  metadata.gz: db5f3b07684338b0a9b63dabf3cc2a00d01adbfcb0c5e8511dd734fc3071d0e7
+  data.tar.gz: aa49b4d56b4eba825fa81ef7a5ff9c75708b92b6036ee5e6439fc1b0821a5e15
 SHA512:
-  metadata.gz: 3c50a67fe8d0d6b65a6e7268c010097a8c191b991c6bcc5f20ad13cbd227c0621e2fe658d1aec1cb646d1c1e6a95439165b618bf56ed8f6811f37cdfb56c0f5f
-  data.tar.gz: b4379981cb0ba478550d60de21a74948ca5b7d7ae5d22210cd1cecf6a349a9bfa3bef32fa574d43483bb9bb1b770e432a621315522ac0eb798ef280fe88c9712
+  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

@@ -18,6 +18,8 @@ Currently supports Kenya's M-Pesa via the Daraja API with plans for additional p
 - **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
@@ -89,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)
@@ -168,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",
@@ -186,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)
@@ -321,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:
 
@@ -328,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.1"
+  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

@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
 
   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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paytree
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Charles Chuck
@@ -123,7 +123,6 @@ files:
 - lib/paytree/response.rb
 - lib/paytree/utils/error_handling.rb
 - lib/paytree/version.rb
-- paytree-0.2.0.gem
 - paytree.gemspec
 - sig/paytree.rbs
 homepage: https://github.com/mundanecodes/paytree
@@ -154,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.6.7
 specification_version: 4
 summary: A Ruby wrapper for the Mpesa API in Kenya.
 test_files: []