paytree 0.2.0

data/README.md

@@ -0,0 +1,341 @@
+# 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.
+
+## Features
+
+- **Simple & Minimal**: Clean API with sensible defaults
+- **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
+- **Security First**: Credential management, no hardcoded secrets
+
+## Quick Start
+
+### 1. Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'paytree'
+```
+
+Or install directly:
+
+```bash
+gem install paytree
+```
+
+### 2. Get M-Pesa API Credentials
+
+1. Register at [Safaricom Developer Portal](https://developer.safaricom.co.ke/)
+2. Create a new app to get your Consumer Key and Secret
+3. For testing, use the sandbox environment
+
+### 3. Basic Setup
+
+```ruby
+# For quick testing (defaults to sandbox)
+Paytree.configure_mpesa(
+  key: "your_consumer_key",
+  secret: "your_consumer_secret",
+  passkey: "your_passkey"
+)
+
+# Make your first payment request
+response = Paytree::Mpesa::StkPush.call(
+  phone_number: "254712345678",
+  amount: 100,
+  reference: "ORDER-001"
+)
+
+puts response.success? ? "Payment initiated!" : "Error: #{response.message}"
+```
+
+---
+
+## Configuration
+
+Paytree uses a single `configure_mpesa` method that defaults to sandbox mode for safety.
+
+### Rails Applications (Recommended)
+
+Create `config/initializers/paytree.rb`:
+
+```ruby
+# config/initializers/paytree.rb
+
+# Development/Testing (defaults to sandbox)
+Paytree.configure_mpesa(
+  key: Rails.application.credentials.mpesa[:consumer_key],
+  secret: Rails.application.credentials.mpesa[:consumer_secret],
+  passkey: Rails.application.credentials.mpesa[:passkey]
+)
+
+# Production (explicitly set sandbox: false)
+# Paytree.configure_mpesa(
+#   key: Rails.application.credentials.mpesa[:consumer_key],
+#   secret: Rails.application.credentials.mpesa[:consumer_secret],
+#   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
+# )
+```
+
+---
+
+## Usage Examples
+
+### STK Push (Customer Payment)
+
+Initiate an M-Pesa STK Push (Lipa na M-Pesa Online) request.
+
+#### Basic STK Push
+
+```ruby
+# Initiate payment request - customer receives prompt on their phone
+response = Paytree::Mpesa::StkPush.call(
+  phone_number: "254712345678",  # Must be in 254XXXXXXXXX format
+  amount: 100,                   # Amount in KES (Kenyan Shillings)
+  reference: "ORDER-001"         # Your internal reference
+)
+
+# Handle the response
+if response.success?
+  puts "Payment request sent! Customer will receive STK prompt."
+  puts "Checkout Request ID: #{response.data['CheckoutRequestID']}"
+
+  # Store the CheckoutRequestID to query status later
+  order.update(mpesa_checkout_id: response.data['CheckoutRequestID'])
+else
+  puts "Payment request failed: #{response.message}"
+  Rails.logger.error "STK Push failed for order #{order.id}: #{response.message}"
+end
+```
+
+**Important**: STK Push only initiates the payment request. The customer must complete payment on their phone. Use STK Query or webhooks to get the final status.
+
+### STK Query (Check Payment Status)
+
+Query the status of a previously initiated STK Push to see if the customer completed payment.
+
+```ruby
+# Check payment status using the CheckoutRequestID from STK Push
+response = Paytree::Mpesa::StkQuery.call(
+  checkout_request_id: "ws_CO_123456789"
+)
+
+if response.success?
+  result_code = response.data["ResultCode"]
+
+  case result_code
+  when "0"
+    puts "Payment completed successfully!"
+    puts "Amount: #{response.data['Amount']}"
+    puts "Receipt: #{response.data['MpesaReceiptNumber']}"
+    puts "Transaction Date: #{response.data['TransactionDate']}"
+
+    # Update your order as paid
+    order.update(status: 'paid', mpesa_receipt: response.data['MpesaReceiptNumber'])
+  when "1032"
+    puts "Payment cancelled by user"
+  when "1037"
+    puts "Payment timed out (user didn't respond)"
+  else
+    puts "Payment failed: #{response.data['ResultDesc']}"
+  end
+else
+  puts "Query failed: #{response.message}"
+end
+```
+
+---
+
+## B2C Payment (Business to Customer)
+
+### Initiate B2C Payment
+
+Send funds directly to a customer’s M-Pesa wallet via the B2C API.
+
+### Example
+```ruby
+response = Paytree::Mpesa::B2C.call(
+  phone_number: "254712345678",
+  amount: 100,
+  reference: "SALAARY2023JULY",
+  remarks: "Monthly salary",
+  occasion: "Payout",
+  command_id: "BusinessPayment" # optional – defaults to "BusinessPayment"
+)
+
+if response.success?
+  puts "B2C payment initiated: #{response.data["ConversationID"]}"
+else
+  puts "Failed to initiate B2C payment: #{response.message}"
+end
+```
+
+---
+
+## C2B (Customer to Business)
+
+### 1  Register Validation & Confirmation URLs
+
+```ruby
+Paytree::Mpesa::C2B.register_urls(
+  short_code:       Payments[:mpesa].shortcode,
+  confirmation_url: "https://your-app.com/mpesa/confirm",
+  validation_url:   "https://your-app.com/mpesa/validate"
+)
+
+response = Paytree::Mpesa::C2B.simulate(
+  phone_number: "254712345678",
+  amount: 75,
+  reference: "INV-42"
+)
+
+if response.success?
+  puts "Simulation OK: #{response.data["CustomerMessage"]}"
+else
+  puts "Simulation failed: #{response.message}"
+end
+```
+
+---
+
+## B2B Payment (Business to Business)
+
+Send funds from one PayBill or BuyGoods shortcode to another.
+
+### Example
+
+```ruby
+response = Paytree::Mpesa::B2B.call(
+  short_code: "174379",                # Sender shortcode (use your actual shortcode)
+  receiver_shortcode: "600111",        # Receiver shortcode
+  amount: 1500,
+  account_reference: "UTIL-APRIL",     # Appears in recipient's statement
+
+  # Optional
+  remarks: "Utility Settlement",
+  command_id: "BusinessPayBill"        # or "BusinessBuyGoods"
+)
+
+if response.success?
+  puts "B2B payment accepted: #{response.message}"
+else
+  puts "B2B failed: #{response.message}"
+end
+```
+
+---
+
+## Response Format
+
+All Paytree operations return a consistent response object with these attributes:
+
+### Response Attributes
+
+```ruby
+response.success?    # Boolean - true if operation succeeded
+response.message     # String - human-readable message
+response.data        # Hash - response data from M-Pesa API
+response.code        # String - M-Pesa response code (if available)
+response.retryable?  # Boolean - true if error is configured as retryable
+```
+
+### Success Response Example
+
+```ruby
+response = Paytree::Mpesa::StkPush.call(
+  phone_number: "254712345678",
+  amount: 100,
+  reference: "ORDER-001"
+)
+
+if response.success?
+  puts response.message  # "STK Push request successful"
+  puts response.data     # {"MerchantRequestID"=>"29115-34620561-1", "CheckoutRequestID"=>"ws_CO_191220191020363925"...}
+end
+```
+
+### Error Response Example
+
+```ruby
+unless response.success?
+  puts response.message  # "Invalid Access Token"
+  puts response.code     # "404.001.03" (if available)
+  puts response.data     # {
+                         #   "requestId" => "",
+                         #   "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"
+    # Implement your retry logic here
+  else
+    puts "This error should not be retried"
+  end
+end
+```
+
+
+
+### Common Response Data Fields
+
+**STK Push Response:**
+- `CheckoutRequestID` - Use this to query payment status
+- `MerchantRequestID` - Internal M-Pesa tracking ID
+- `CustomerMessage` - Message shown to customer
+
+**STK Query Response:**
+- `ResultCode` - "0" = success, "1032" = cancelled, "1037" = timeout
+- `ResultDesc` - Human-readable result description
+- `MpesaReceiptNumber` - M-Pesa transaction receipt (on success)
+- `Amount` - Transaction amount
+- `TransactionDate` - When payment was completed
+
+**B2C/B2B Response:**
+- `ConversationID` - Transaction tracking ID
+- `OriginatorConversationID` - Your internal tracking ID
+- `ResponseDescription` - Status message
+
+### Retryable Errors
+
+Paytree allows you to configure which error codes should be considered retryable. This is useful for building resilient payment systems that can automatically retry transient errors.
+
+**Common retryable errors:**
+- `"429.001.01"` - Rate limit exceeded
+- `"500.001.02"` - Temporary server error
+- `"503.001.01"` - Service temporarily unavailable
+
+Configure retryable errors during setup:
+
+```ruby
+Paytree.configure_mpesa(
+  key: "YOUR_KEY",
+  secret: "YOUR_SECRET",
+  retryable_errors: ["429.001.01", "500.001.02", "503.001.01"]
+)
+```
+
+Then check if an error response can be retried:
+
+```ruby
+response = Paytree::Mpesa::StkPush.call(...)
+
+unless response.success?
+  if response.retryable?
+    # Implement exponential backoff retry logic
+    retry_with_backoff
+  else
+    # Handle permanent error
+    handle_permanent_failure(response)
+  end
+end
+```
+
+---

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/paytree/concerns/feature_set.rb

@@ -0,0 +1,15 @@
+module Paytree
+  module FeatureSet
+    def supports(*list)
+      @features = list.map(&:to_sym)
+    end
+
+    def features
+      @features || []
+    end
+
+    def supports?(feature)
+      features.include?(feature.to_sym)
+    end
+  end
+end

data/lib/paytree/configs/mpesa.rb

@@ -0,0 +1,35 @@
+require "logger"
+
+module Paytree
+  module Configs
+    class Mpesa
+      attr_accessor :key, :secret, :shortcode, :passkey, :adapter,
+        :initiator_name, :initiator_password, :sandbox,
+        :extras, :timeout, :retryable_errors
+
+      def initialize
+        @extras = {}
+        @logger = nil
+        @mutex = Mutex.new
+        @timeout = 30      # Default 30 second timeout
+        @retryable_errors = []  # Default empty array
+      end
+
+      def base_url
+        sandbox ? "https://sandbox.safaricom.co.ke" : "https://api.safaricom.co.ke"
+      end
+
+      def logger
+        @mutex.synchronize do
+          @logger ||= Logger.new($stdout)
+        end
+      end
+
+      def logger=(new_logger)
+        @mutex.synchronize do
+          @logger = new_logger
+        end
+      end
+    end
+  end
+end

data/lib/paytree/configuration_registry.rb

@@ -0,0 +1,39 @@
+module Paytree
+  class ConfigurationRegistry
+    def initialize
+      @configs = {}
+      @mutex = Mutex.new
+    end
+
+    def configure(provider, config_class)
+      raise ArgumentError, "config_class must be a Class" unless config_class.is_a?(Class)
+
+      config = config_class.new
+      yield config if block_given?
+
+      @mutex.synchronize do
+        @configs[provider] = config
+      end
+    end
+
+    def store_config(provider, config_instance)
+      @mutex.synchronize do
+        @configs[provider] = config_instance
+      end
+    end
+
+    def [](provider)
+      @mutex.synchronize do
+        @configs.fetch(provider) do
+          raise ArgumentError, "No config registered for provider: #{provider}"
+        end
+      end
+    end
+
+    def to_h
+      @mutex.synchronize do
+        @configs.dup
+      end
+    end
+  end
+end

data/lib/paytree/errors.rb

@@ -0,0 +1,17 @@
+module Paytree
+  module Errors
+    Base = Class.new(StandardError)
+
+    MpesaCertMissing = Class.new(Base)
+    MpesaTokenError = Class.new(Base)
+    MpesaMalformedResponse = Class.new(Base)
+    MpesaResponseError = Class.new(Base)
+    MpesaClientError = Class.new(Base)
+    MpesaServerError = Class.new(Base)
+    MpesaHttpError = Class.new(Base)
+
+    ConfigurationError = Class.new(Base)
+    UnsupportedOperation = Class.new(Base)
+    ValidationError = Class.new(Base)
+  end
+end

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

@@ -0,0 +1,39 @@
+require "paytree/mpesa/adapters/daraja/base"
+
+module Paytree
+  module Mpesa
+    module Adapters
+      module Daraja
+        class B2B < Base
+          ENDPOINT = "/mpesa/b2b/v1/paymentrequest"
+
+          class << self
+            def call(short_code:, receiver_shortcode:, amount:, account_reference:, **opts)
+              with_error_handling(context: :b2b) do
+                command_id = opts[:command_id] || "BusinessPayBill"
+                validate_for(:b2b, short_code:, receiver_shortcode:, account_reference:, amount:, command_id:)
+
+                payload = {
+                  Initiator: config.initiator_name,
+                  SecurityCredential: encrypt_credential(config),
+                  SenderIdentifierType: "4",
+                  ReceiverIdentifierType: "4",
+                  Amount: amount,
+                  PartyA: short_code,
+                  PartyB: receiver_shortcode,
+                  AccountReference: account_reference,
+                  CommandID: command_id,
+                  Remarks: opts[:remarks] || "B2B Payment",
+                  QueueTimeOutURL: config.extras[:timeout_url],
+                  ResultURL: config.extras[:result_url]
+                }.compact
+
+                post_to_mpesa(:b2b, ENDPOINT, payload)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+require "paytree/mpesa/adapters/daraja/base"
+
+module Paytree
+  module Mpesa
+    module Adapters
+      module Daraja
+        class B2C < Base
+          ENDPOINT = "/mpesa/b2c/v1/paymentrequest"
+
+          class << self
+            def call(phone_number:, amount:, **opts)
+              with_error_handling(context: :b2c) do
+                validate_for(:b2c, phone_number:, amount:)
+
+                payload = {
+                  InitiatorName: config.initiator_name,
+                  SecurityCredential: encrypt_credential(config),
+                  Amount: amount,
+                  PartyA: config.shortcode,
+                  PartyB: phone_number,
+                  QueueTimeOutURL: config.extras[:timeout_url],
+                  ResultURL: config.extras[:result_url],
+                  CommandID: opts[:command_id] || "BusinessPayment",
+                  Remarks: opts[:remarks] || "OK",
+                  Occasion: opts[:occasion] || "Payment"
+                }.compact
+
+                post_to_mpesa(:b2c, ENDPOINT, payload)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+require "base64"
+require_relative "response_helpers"
+require_relative "../../../utils/error_handling"
+
+module Paytree
+  module Mpesa
+    module Adapters
+      module Daraja
+        class Base
+          class << self
+            include Paytree::Utils::ErrorHandling
+            include Paytree::Mpesa::Adapters::Daraja::ResponseHelpers
+
+            def config = Paytree[:mpesa]
+
+            def connection
+              @connection ||= Faraday.new(url: config.base_url) do |conn|
+                conn.options.timeout = config.timeout
+                conn.options.open_timeout = config.timeout / 2
+
+                conn.request :json
+                conn.response :json, content_type: "application/json"
+              end
+            end
+
+            def post_to_mpesa(operation, endpoint, payload)
+              build_response(
+                connection.post(endpoint, payload.to_json, headers),
+                operation
+              )
+            end
+
+            def headers
+              {"Authorization" => "Bearer #{token}", "Content-Type" => "application/json"}
+            end
+
+            def token
+              return @token if token_valid?
+
+              fetch_token
+            end
+
+            def encrypt_credential(config)
+              cert_path = config.extras[:cert_path]
+              unless cert_path && File.exist?(cert_path)
+                raise Paytree::Errors::MpesaCertMissing,
+                  "Missing or unreadable certificate at #{cert_path}"
+              end
+
+              certificate = OpenSSL::X509::Certificate.new(File.read(cert_path))
+              encrypted = certificate.public_key.public_encrypt(config.initiator_password)
+              Base64.strict_encode64(encrypted)
+            rescue OpenSSL::OpenSSLError => e
+              raise Paytree::Errors::MpesaCertMissing,
+                "Failed to encrypt password with certificate #{cert_path}: #{e.message}"
+            end
+
+            # ------------------------------------------------------------------
+            # Validation rules
+            # ------------------------------------------------------------------
+            VALIDATIONS = {
+              c2b_register: {required: %i[short_code confirmation_url validation_url]},
+              c2b_simulate: {required: %i[phone_number amount reference]},
+              stk_push: {required: %i[phone_number amount reference]},
+              b2c: {required: %i[phone_number amount], config: %i[result_url]},
+              b2b: {
+                required: %i[short_code receiver_shortcode account_reference amount],
+                config: %i[result_url timeout_url],
+                command_id: %w[BusinessPayBill BusinessBuyGoods]
+              }
+            }.freeze
+
+            def validate_for(operation, params = {})
+              rules = VALIDATIONS[operation] ||
+                raise(Paytree::Errors::UnsupportedOperation, "Unknown operation: #{operation}")
+
+              Array(rules[:required]).each { |field| validate_field(field, params[field]) }
+
+              Array(rules[:config]).each do |key|
+                unless config.extras[key]
+                  raise Paytree::Errors::ConfigurationError, "Missing `#{key}` in Mpesa extras config"
+                end
+              end
+
+              if (allowed = rules[:command_id]) && !allowed.include?(params[:command_id])
+                raise Paytree::Errors::ValidationError,
+                  "command_id must be one of: #{allowed.join(", ")}"
+              end
+            end
+
+            def validate_field(field, value)
+              case field
+              when :amount
+                unless value.is_a?(Numeric) && value >= 1
+                  raise Paytree::Errors::ValidationError,
+                    "amount must be a positive number"
+                end
+              when :phone_number
+                phone_regex = /^254\d{9}$/
+                unless value.to_s.match?(phone_regex)
+                  raise Paytree::Errors::ValidationError,
+                    "phone_number must be a valid Kenyan format (254XXXXXXXXX)"
+                end
+              else
+                raise Paytree::Errors::ValidationError, "#{field} cannot be blank" if value.to_s.strip.empty?
+              end
+            end
+
+            private
+
+            def fetch_token
+              cred = Base64.strict_encode64("#{config.key}:#{config.secret}")
+
+              response = connection.get("/oauth/v1/generate", grant_type: "client_credentials") do |r|
+                r.headers["Authorization"] = "Basic #{cred}"
+              end
+
+              data = response.body
+              @token = data["access_token"]
+              @token_expiry = Time.now + data["expires_in"].to_i
+              @token
+            rescue Faraday::Error => e
+              raise Paytree::Errors::MpesaTokenError, "Unable to fetch token: #{e.message}"
+            end
+
+            def token_valid?
+              @token && @token_expiry && Time.now < @token_expiry
+            end
+          end
+        end
+      end
+    end
+  end
+end