malipopay 1.0.0

data/lib/malipopay/resources/payments.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module MaliPoPay
+  module Resources
+    class Payments
+      def initialize(http_client)
+        @http = http_client
+      end
+
+      # Initiate a payment (collection or disbursement)
+      # @param params [Hash] Payment parameters
+      # @return [Hash] Payment response
+      def initiate(params)
+        @http.post("/api/v1/payment", body: params)
+      end
+
+      # Initiate a mobile money collection
+      # @param params [Hash] Collection parameters (amount, phone, provider, reference, etc.)
+      # @return [Hash] Collection response
+      def collect(params)
+        @http.post("/api/v1/payment/collection", body: params)
+      end
+
+      # Initiate a disbursement (send money)
+      # @param params [Hash] Disbursement parameters
+      # @return [Hash] Disbursement response
+      def disburse(params)
+        @http.post("/api/v1/payment/disbursement", body: params)
+      end
+
+      # Process an instant payment
+      # @param params [Hash] Payment parameters
+      # @return [Hash] Payment response
+      def pay_now(params)
+        @http.post("/api/v1/payment/now", body: params)
+      end
+
+      # Verify a payment by reference
+      # @param reference [String] Payment reference
+      # @return [Hash] Payment verification details
+      def verify(reference)
+        @http.get("/api/v1/payment/verify/#{reference}")
+      end
+
+      # Get a payment by reference
+      # @param reference [String] Payment reference
+      # @return [Hash] Payment details
+      def get(reference)
+        @http.get("/api/v1/payment/reference/#{reference}")
+      end
+
+      # List all payments
+      # @param params [Hash] Query parameters (page, limit, etc.)
+      # @return [Hash] Paginated list of payments
+      def list(params = {})
+        @http.get("/api/v1/payment", params: params)
+      end
+
+      # Search payments
+      # @param params [Hash] Search parameters
+      # @return [Hash] Search results
+      def search(params = {})
+        @http.get("/api/v1/payment/search", params: params)
+      end
+
+      # Approve a pending payment
+      # @param params [Hash] Approval parameters (reference, etc.)
+      # @return [Hash] Approval response
+      def approve(params)
+        @http.post("/api/v1/payment/approve", body: params)
+      end
+
+      # Retry a failed collection
+      # @param reference [String] Payment reference to retry
+      # @return [Hash] Retry response
+      def retry_collection(reference)
+        @http.get("/api/v1/payment/retry/#{reference}")
+      end
+
+      # Create a payment link
+      # @param params [Hash] Payment link parameters
+      # @return [Hash] Payment link response
+      def create_link(params)
+        @http.post("/api/v1/pay", body: params)
+      end
+    end
+  end
+end

data/lib/malipopay/resources/products.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module MaliPoPay
+  module Resources
+    class Products
+      def initialize(http_client)
+        @http = http_client
+      end
+
+      # Create a new product
+      # @param params [Hash] Product parameters (name, price, description, etc.)
+      # @return [Hash] Created product
+      def create(params)
+        @http.post("/api/v1/product", body: params)
+      end
+
+      # List all products
+      # @param params [Hash] Query parameters (page, limit, etc.)
+      # @return [Hash] Paginated list of products
+      def list(params = {})
+        @http.get("/api/v1/product", params: params)
+      end
+
+      # Get a product by ID
+      # @param id [String] Product ID
+      # @return [Hash] Product details
+      def get(id)
+        @http.get("/api/v1/product/#{id}")
+      end
+
+      # Get a product by product number
+      # @param number [String] Product number
+      # @return [Hash] Product details
+      def get_by_number(number)
+        @http.get("/api/v1/product", params: { productNumber: number })
+      end
+
+      # Update an existing product
+      # @param id [String] Product ID
+      # @param params [Hash] Updated product parameters
+      # @return [Hash] Updated product
+      def update(id, params)
+        @http.put("/api/v1/product/#{id}", body: params)
+      end
+    end
+  end
+end

data/lib/malipopay/resources/references.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module MaliPoPay
+  module Resources
+    class References
+      def initialize(http_client)
+        @http = http_client
+      end
+
+      # List all supported banks
+      # @param params [Hash] Query parameters
+      # @return [Hash] List of banks
+      def banks(params = {})
+        @http.get("/api/v1/banks", params: params)
+      end
+
+      # List all supported financial institutions
+      # @param params [Hash] Query parameters
+      # @return [Hash] List of institutions
+      def institutions(params = {})
+        @http.get("/api/v1/banks", params: params)
+      end
+
+      # List all supported currencies
+      # @param params [Hash] Query parameters
+      # @return [Hash] List of currencies
+      def currencies(params = {})
+        @http.get("/api/v1/currency", params: params)
+      end
+
+      # List all supported countries
+      # @param params [Hash] Query parameters
+      # @return [Hash] List of countries
+      def countries(params = {})
+        @http.get("/api/v1/countries", params: params)
+      end
+
+      # List business types
+      # @param params [Hash] Query parameters
+      # @return [Hash] List of business types
+      def business_types(params = {})
+        @http.get("/api/v1/countries", params: params.merge(type: "business"))
+      end
+    end
+  end
+end

data/lib/malipopay/resources/sms.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module MaliPoPay
+  module Resources
+    class Sms
+      def initialize(http_client)
+        @http = http_client
+      end
+
+      # Send a single SMS
+      # @param params [Hash] SMS parameters (to, message, senderId, etc.)
+      # @return [Hash] SMS send response
+      def send_sms(params)
+        @http.post("/sms/", body: params)
+      end
+
+      # Send bulk SMS
+      # @param params [Hash] Bulk SMS parameters (messages array, senderId, etc.)
+      # @return [Hash] Bulk SMS response
+      def send_bulk(params)
+        @http.post("/sms/bulk", body: params)
+      end
+
+      # Schedule an SMS for later delivery
+      # @param params [Hash] Schedule parameters (to, message, senderId, scheduledAt, etc.)
+      # @return [Hash] Scheduled SMS response
+      def schedule(params)
+        @http.post("/sms/schedule", body: params)
+      end
+    end
+  end
+end

data/lib/malipopay/resources/transactions.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module MaliPoPay
+  module Resources
+    class Transactions
+      def initialize(http_client)
+        @http = http_client
+      end
+
+      # List all transactions
+      # @param params [Hash] Query parameters (page, limit, type, status, etc.)
+      # @return [Hash] Paginated list of transactions
+      def list(params = {})
+        @http.get("/api/v1/transactions", params: params)
+      end
+
+      # Get a transaction by ID
+      # @param id [String] Transaction ID
+      # @return [Hash] Transaction details
+      def get(id)
+        @http.get("/api/v1/transactions/#{id}")
+      end
+
+      # Search transactions
+      # @param params [Hash] Search parameters (query, dateFrom, dateTo, etc.)
+      # @return [Hash] Search results
+      def search(params = {})
+        @http.get("/api/v1/transactions/search", params: params)
+      end
+
+      # Paginate through transactions
+      # @param params [Hash] Pagination parameters (page, limit)
+      # @yield [Hash] Each page of transactions
+      # @return [Enumerator] If no block given
+      def paginate(params = {})
+        return enum_for(:paginate, params) unless block_given?
+
+        page = params.fetch(:page, 1)
+        loop do
+          result = list(params.merge(page: page))
+          yield result
+
+          records = result["data"] || result["records"] || []
+          break if records.empty?
+
+          page += 1
+        end
+      end
+
+      # Get tariff information
+      # @param params [Hash] Query parameters
+      # @return [Hash] Tariff details
+      def tariffs(params = {})
+        @http.get("/api/v1/transactions", params: params.merge(type: "tariff"))
+      end
+    end
+  end
+end

data/lib/malipopay/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MaliPoPay
+  VERSION = "1.0.0"
+end

data/lib/malipopay/webhooks/verifier.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "json"
+
+module MaliPoPay
+  module Webhooks
+    class Verifier
+      TOLERANCE_IN_SECONDS = 300 # 5 minutes
+
+      def initialize(secret)
+        @secret = secret
+      end
+
+      # Verify a webhook signature
+      # @param payload [String] Raw request body
+      # @param signature [String] Signature from X-MaliPoPay-Signature header
+      # @param timestamp [String, nil] Timestamp from X-MaliPoPay-Timestamp header
+      # @return [Boolean] Whether the signature is valid
+      def verify(payload, signature, timestamp: nil)
+        return false if signature.nil? || signature.empty?
+
+        if timestamp
+          ts = timestamp.to_i
+          return false if (Time.now.to_i - ts).abs > TOLERANCE_IN_SECONDS
+        end
+
+        expected = self.class.sign(payload, @secret, timestamp: timestamp)
+        secure_compare(expected, signature)
+      end
+
+      # Verify and parse a webhook event
+      # @param payload [String] Raw request body
+      # @param signature [String] Signature from header
+      # @param timestamp [String, nil] Timestamp from header
+      # @return [Hash] Parsed event data
+      # @raise [MaliPoPay::Error] If signature is invalid
+      def construct_event(payload, signature, timestamp: nil)
+        unless verify(payload, signature, timestamp: timestamp)
+          raise MaliPoPay::AuthenticationError.new("Invalid webhook signature")
+        end
+
+        JSON.parse(payload)
+      end
+
+      # Generate an HMAC signature for a payload
+      # @param payload [String] Raw payload string
+      # @param secret [String] Webhook secret
+      # @param timestamp [String, nil] Optional timestamp to include in signature
+      # @return [String] Hex-encoded HMAC-SHA256 signature
+      def self.sign(payload, secret, timestamp: nil)
+        signed_payload = timestamp ? "#{timestamp}.#{payload}" : payload
+        OpenSSL::HMAC.hexdigest("SHA256", secret, signed_payload)
+      end
+
+      private
+
+      def secure_compare(a, b)
+        return false unless a.bytesize == b.bytesize
+
+        l = a.unpack("C*")
+        r = b.unpack("C*")
+        result = 0
+        l.zip(r) { |x, y| result |= x ^ y }
+        result.zero?
+      end
+    end
+  end
+end

data/lib/malipopay.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "malipopay/version"
+require_relative "malipopay/errors"
+require_relative "malipopay/http_client"
+require_relative "malipopay/client"
+
+# Resources
+require_relative "malipopay/resources/payments"
+require_relative "malipopay/resources/customers"
+require_relative "malipopay/resources/invoices"
+require_relative "malipopay/resources/products"
+require_relative "malipopay/resources/transactions"
+require_relative "malipopay/resources/account"
+require_relative "malipopay/resources/sms"
+require_relative "malipopay/resources/references"
+
+# Webhooks
+require_relative "malipopay/webhooks/verifier"
+
+module MaliPoPay
+  # Convenience method to create a new client
+  #
+  # @param options [Hash] Options passed to MaliPoPay::Client.new
+  # @return [MaliPoPay::Client]
+  def self.client(**options)
+    Client.new(**options)
+  end
+end

data/malipopay.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "lib/malipopay/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "malipopay"
+  spec.version       = MaliPoPay::VERSION
+  spec.authors       = ["Lockwood Technology Ltd"]
+  spec.email         = ["developers@malipopay.co.tz"]
+
+  spec.summary       = "Official Ruby SDK for the MaliPoPay payment platform"
+  spec.description   = "Ruby client library for integrating with MaliPoPay payment APIs. " \
+                        "Supports mobile money collections, disbursements, invoicing, " \
+                        "SMS, customer management, and more."
+  spec.homepage      = "https://github.com/malipopay/malipopay-ruby"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"]   = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://docs.malipopay.co.tz"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?("spec/", "examples/", ".git", ".github")
+    end
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday", "~> 2.0"
+  spec.add_dependency "faraday-retry", "~> 2.0"
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "webmock", "~> 3.0"
+  spec.add_development_dependency "rubocop", "~> 1.0"
+end

metadata

@@ -0,0 +1,174 @@
+--- !ruby/object:Gem::Specification
+name: malipopay
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Lockwood Technology Ltd
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-04-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Ruby client library for integrating with MaliPoPay payment APIs. Supports
+  mobile money collections, disbursements, invoicing, SMS, customer management, and
+  more.
+email:
+- developers@malipopay.co.tz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- docs/configuration.md
+- docs/customers.md
+- docs/error-handling.md
+- docs/getting-started.md
+- docs/invoices.md
+- docs/payments.md
+- docs/sms.md
+- docs/webhooks.md
+- lib/malipopay.rb
+- lib/malipopay/client.rb
+- lib/malipopay/errors.rb
+- lib/malipopay/http_client.rb
+- lib/malipopay/resources/account.rb
+- lib/malipopay/resources/customers.rb
+- lib/malipopay/resources/invoices.rb
+- lib/malipopay/resources/payments.rb
+- lib/malipopay/resources/products.rb
+- lib/malipopay/resources/references.rb
+- lib/malipopay/resources/sms.rb
+- lib/malipopay/resources/transactions.rb
+- lib/malipopay/version.rb
+- lib/malipopay/webhooks/verifier.rb
+- malipopay.gemspec
+homepage: https://github.com/malipopay/malipopay-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/malipopay/malipopay-ruby
+  source_code_uri: https://github.com/malipopay/malipopay-ruby
+  changelog_uri: https://github.com/malipopay/malipopay-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://docs.malipopay.co.tz
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Official Ruby SDK for the MaliPoPay payment platform
+test_files: []