malipopay 1.0.0

data/docs/webhooks.md

@@ -0,0 +1,219 @@
+# Webhooks
+
+Webhooks let you receive real-time notifications when events happen in MaliPoPay -- payment completed, payment failed, disbursement processed, etc. Instead of polling the API, you register a URL and MaliPoPay sends HTTP POST requests to it.
+
+## How Webhooks Work
+
+1. You register a webhook URL in your MaliPoPay dashboard at [app.malipopay.co.tz](https://app.malipopay.co.tz) under **Settings > Webhooks**
+2. MaliPoPay generates a **webhook signing secret** for you
+3. When an event occurs, MaliPoPay sends a POST request to your URL with:
+   - The event payload as JSON in the request body
+   - An `X-MaliPoPay-Signature` header containing the HMAC-SHA256 signature
+4. Your endpoint verifies the signature and processes the event
+
+## Event Types
+
+| Event | Description |
+|-------|-------------|
+| `payment.completed` | A collection was successfully completed |
+| `payment.failed` | A collection failed (timeout, insufficient funds, cancelled) |
+| `disbursement.completed` | A disbursement was sent successfully |
+| `disbursement.failed` | A disbursement failed |
+| `invoice.paid` | An invoice was fully paid |
+| `invoice.partially_paid` | A partial payment was recorded |
+
+## Sinatra Webhook Endpoint
+
+A lightweight webhook endpoint using Sinatra:
+
+```ruby
+require 'sinatra'
+require 'json'
+require 'malipopay'
+
+WEBHOOK_SECRET = ENV.fetch('MALIPOPAY_WEBHOOK_SECRET')
+verifier = MaliPoPay::Webhooks::Verifier.new(WEBHOOK_SECRET)
+
+post '/webhooks/malipopay' do
+  payload = request.body.read
+  signature = request.env['HTTP_X_MALIPOPAY_SIGNATURE']
+
+  unless signature
+    halt 400, 'Missing signature'
+  end
+
+  begin
+    event = verifier.construct_event(payload, signature)
+
+    case event['event_type']
+    when 'payment.completed'
+      puts "Payment completed: #{event['reference']}, Amount: TZS #{event['amount']}"
+      # Update your order/invoice status in the database
+
+    when 'payment.failed'
+      puts "Payment failed: #{event['reference']}, Reason: #{event['reason']}"
+      # Notify the customer, retry, or cancel the order
+
+    when 'disbursement.completed'
+      puts "Disbursement sent: #{event['reference']}"
+
+    else
+      puts "Unhandled event type: #{event['event_type']}"
+    end
+
+    status 200
+    'OK'
+  rescue MaliPoPay::Error => e
+    puts "Webhook verification failed: #{e.message}"
+    halt 401, 'Invalid signature'
+  end
+end
+```
+
+## Rails Controller Example
+
+A full Rails controller for handling MaliPoPay webhooks:
+
+```ruby
+# app/controllers/webhooks/malipopay_controller.rb
+module Webhooks
+  class MalipopayController < ApplicationController
+    skip_before_action :verify_authenticity_token
+
+    def create
+      payload = request.body.read
+      signature = request.headers['X-MaliPoPay-Signature']
+
+      unless signature.present?
+        render json: { error: 'Missing signature' }, status: :bad_request
+        return
+      end
+
+      begin
+        event = webhook_verifier.construct_event(payload, signature)
+        handle_event(event)
+        head :ok
+      rescue MaliPoPay::Error => e
+        Rails.logger.error("Webhook verification failed: #{e.message}")
+        head :unauthorized
+      end
+    end
+
+    private
+
+    def webhook_verifier
+      @webhook_verifier ||= MaliPoPay::Webhooks::Verifier.new(
+        ENV.fetch('MALIPOPAY_WEBHOOK_SECRET')
+      )
+    end
+
+    def handle_event(event)
+      case event['event_type']
+      when 'payment.completed'
+        handle_payment_completed(event)
+      when 'payment.failed'
+        handle_payment_failed(event)
+      when 'disbursement.completed'
+        Rails.logger.info("Disbursement completed: #{event['reference']}")
+      when 'invoice.paid'
+        handle_invoice_paid(event)
+      else
+        Rails.logger.info("Unhandled webhook event: #{event['event_type']}")
+      end
+    end
+
+    def handle_payment_completed(event)
+      Rails.logger.info(
+        "Payment completed: #{event['reference']}, " \
+        "Amount: TZS #{event['amount']}"
+      )
+
+      # Update your order status
+      order = Order.find_by(reference: event['reference'])
+      order&.mark_as_paid!(
+        transaction_id: event['transaction_id'],
+        provider: event['provider']
+      )
+    end
+
+    def handle_payment_failed(event)
+      Rails.logger.warn(
+        "Payment failed: #{event['reference']}, " \
+        "Reason: #{event['reason']}"
+      )
+
+      order = Order.find_by(reference: event['reference'])
+      order&.mark_as_failed!(reason: event['reason'])
+    end
+
+    def handle_invoice_paid(event)
+      invoice = Invoice.find_by(external_id: event['reference'])
+      invoice&.mark_as_paid!
+    end
+  end
+end
+```
+
+Add the route in `config/routes.rb`:
+
+```ruby
+namespace :webhooks do
+  post 'malipopay', to: 'malipopay#create'
+end
+```
+
+## Signature Verification
+
+Every webhook request includes an `X-MaliPoPay-Signature` header. The signature is an HMAC-SHA256 hash of the raw request body, signed with your webhook secret.
+
+The `MaliPoPay::Webhooks::Verifier` handles this for you:
+
+```ruby
+verifier = MaliPoPay::Webhooks::Verifier.new('your_webhook_secret')
+
+# Just verify (returns true/false)
+valid = verifier.verify(payload, signature)
+
+# Verify and parse in one step (raises on failure)
+event = verifier.construct_event(payload, signature)
+```
+
+### Manual Verification
+
+If you need to verify the signature manually without using the SDK:
+
+```ruby
+require 'openssl'
+
+def verify_manually(payload, signature, secret)
+  expected = OpenSSL::HMAC.hexdigest('SHA256', secret, payload)
+  Rack::Utils.secure_compare(expected, signature)
+end
+```
+
+## Best Practices
+
+1. **Always verify signatures.** Never process a webhook without checking the signature. This prevents spoofed requests.
+
+2. **Return 200 quickly.** Process the event asynchronously if needed (e.g., with Sidekiq or ActiveJob). MaliPoPay expects a response within 30 seconds. If you don't return 200, the webhook will be retried.
+
+3. **Handle duplicates.** Webhooks may be delivered more than once. Use the `reference` or `transaction_id` as an idempotency key.
+
+4. **Log everything.** Log the raw payload and event type for debugging and audit trails.
+
+5. **Use HTTPS.** Your webhook endpoint must be accessible over HTTPS in production.
+
+6. **Process asynchronously in Rails.** Offload heavy work to a background job:
+
+```ruby
+def handle_payment_completed(event)
+  PaymentCompletedJob.perform_later(event.to_json)
+  # Return 200 immediately -- the job processes the event
+end
+```
+
+## Next Steps
+
+- [Error Handling](./error-handling.md) -- handle webhook verification failures
+- [Payments](./payments.md) -- understand the payment flow that triggers webhooks
+- [Configuration](./configuration.md) -- client setup

data/lib/malipopay/client.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module MaliPoPay
+  class Client
+    attr_reader :http_client, :webhook_secret
+
+    # Initialize a new MaliPoPay client
+    #
+    # @param api_key [String] Your MaliPoPay API token
+    # @param environment [Symbol] :production or :uat (default: :production)
+    # @param base_url [String, nil] Override the base URL
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    # @param retries [Integer] Number of retries on failure (default: 2)
+    # @param webhook_secret [String, nil] Secret for verifying webhooks
+    def initialize(api_key:, environment: :production, base_url: nil, timeout: 30, retries: 2, webhook_secret: nil)
+      raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
+
+      @http_client = HttpClient.new(
+        api_key: api_key,
+        environment: environment,
+        base_url: base_url,
+        timeout: timeout,
+        retries: retries
+      )
+      @webhook_secret = webhook_secret
+    end
+
+    # @return [MaliPoPay::Resources::Payments]
+    def payments
+      @payments ||= Resources::Payments.new(@http_client)
+    end
+
+    # @return [MaliPoPay::Resources::Customers]
+    def customers
+      @customers ||= Resources::Customers.new(@http_client)
+    end
+
+    # @return [MaliPoPay::Resources::Invoices]
+    def invoices
+      @invoices ||= Resources::Invoices.new(@http_client)
+    end
+
+    # @return [MaliPoPay::Resources::Products]
+    def products
+      @products ||= Resources::Products.new(@http_client)
+    end
+
+    # @return [MaliPoPay::Resources::Transactions]
+    def transactions
+      @transactions ||= Resources::Transactions.new(@http_client)
+    end
+
+    # @return [MaliPoPay::Resources::Account]
+    def account
+      @account ||= Resources::Account.new(@http_client)
+    end
+
+    # @return [MaliPoPay::Resources::Sms]
+    def sms
+      @sms ||= Resources::Sms.new(@http_client)
+    end
+
+    # @return [MaliPoPay::Resources::References]
+    def references
+      @references ||= Resources::References.new(@http_client)
+    end
+
+    # @return [MaliPoPay::Webhooks::Verifier]
+    # @raise [ArgumentError] if webhook_secret was not provided
+    def webhooks
+      raise ArgumentError, "webhook_secret is required for webhook verification" unless @webhook_secret
+
+      @webhooks ||= Webhooks::Verifier.new(@webhook_secret)
+    end
+  end
+end

data/lib/malipopay/errors.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module MaliPoPay
+  # Base error class for all MaliPoPay errors
+  class Error < StandardError
+    attr_reader :http_status, :response_body
+
+    def initialize(message = nil, http_status: nil, response_body: nil)
+      @http_status = http_status
+      @response_body = response_body
+      super(message)
+    end
+  end
+
+  # Raised when the API key is missing or invalid (401)
+  class AuthenticationError < Error; end
+
+  # Raised when the API key lacks permissions for the request (403)
+  class PermissionError < Error; end
+
+  # Raised when the requested resource is not found (404)
+  class NotFoundError < Error; end
+
+  # Raised when request parameters fail validation (400/422)
+  class ValidationError < Error
+    attr_reader :errors
+
+    def initialize(message = nil, errors: nil, **kwargs)
+      @errors = errors
+      super(message, **kwargs)
+    end
+  end
+
+  # Raised when the API rate limit is exceeded (429)
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **kwargs)
+      @retry_after = retry_after
+      super(message, **kwargs)
+    end
+  end
+
+  # Raised for general API errors (5xx, unexpected responses)
+  class ApiError < Error; end
+
+  # Raised when a network connection error occurs
+  class ConnectionError < Error; end
+end

data/lib/malipopay/http_client.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+
+module MaliPoPay
+  class HttpClient
+    BASE_URLS = {
+      production: "https://core-prod.malipopay.co.tz",
+      uat: "https://core-uat.malipopay.co.tz"
+    }.freeze
+
+    RETRYABLE_STATUS_CODES = [429, 500, 502, 503, 504].freeze
+
+    def initialize(api_key:, environment: :production, base_url: nil, timeout: 30, retries: 2)
+      @api_key = api_key
+      @base_url = base_url || BASE_URLS.fetch(environment.to_sym) do
+        raise ArgumentError, "Invalid environment: #{environment}. Use :production or :uat"
+      end
+      @timeout = timeout
+      @retries = retries
+    end
+
+    def get(path, params: {})
+      execute(:get, path, params: params)
+    end
+
+    def post(path, body: {})
+      execute(:post, path, body: body)
+    end
+
+    def put(path, body: {})
+      execute(:put, path, body: body)
+    end
+
+    def delete(path, params: {})
+      execute(:delete, path, params: params)
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: @base_url) do |conn|
+        conn.request :json
+        conn.response :json, content_type: /\bjson$/
+
+        conn.request :retry,
+                     max: @retries,
+                     interval: 0.5,
+                     interval_randomness: 0.5,
+                     backoff_factor: 2,
+                     retry_statuses: RETRYABLE_STATUS_CODES,
+                     methods: %i[get post put delete],
+                     retry_block: ->(env, _opts, _retries, _exc) {
+                       env.request_headers["X-Retry-Count"] = _retries.to_s
+                     }
+
+        conn.headers["apiToken"] = @api_key
+        conn.headers["Content-Type"] = "application/json"
+        conn.headers["Accept"] = "application/json"
+        conn.headers["User-Agent"] = "malipopay-ruby/#{MaliPoPay::VERSION}"
+
+        conn.options.timeout = @timeout
+        conn.options.open_timeout = 10
+
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def execute(method, path, params: {}, body: {})
+      response = case method
+                 when :get
+                   connection.get(path) { |req| req.params = params unless params.empty? }
+                 when :post
+                   connection.post(path, body)
+                 when :put
+                   connection.put(path, body)
+                 when :delete
+                   connection.delete(path) { |req| req.params = params unless params.empty? }
+                 end
+
+      handle_response(response)
+    rescue Faraday::ConnectionFailed => e
+      raise MaliPoPay::ConnectionError.new("Connection failed: #{e.message}")
+    rescue Faraday::TimeoutError => e
+      raise MaliPoPay::ConnectionError.new("Request timed out: #{e.message}")
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        response.body
+      when 400
+        raise MaliPoPay::ValidationError.new(
+          error_message(response),
+          errors: response.body&.dig("errors"),
+          http_status: response.status,
+          response_body: response.body
+        )
+      when 401
+        raise MaliPoPay::AuthenticationError.new(
+          error_message(response),
+          http_status: response.status,
+          response_body: response.body
+        )
+      when 403
+        raise MaliPoPay::PermissionError.new(
+          error_message(response),
+          http_status: response.status,
+          response_body: response.body
+        )
+      when 404
+        raise MaliPoPay::NotFoundError.new(
+          error_message(response),
+          http_status: response.status,
+          response_body: response.body
+        )
+      when 422
+        raise MaliPoPay::ValidationError.new(
+          error_message(response),
+          errors: response.body&.dig("errors"),
+          http_status: response.status,
+          response_body: response.body
+        )
+      when 429
+        raise MaliPoPay::RateLimitError.new(
+          error_message(response),
+          retry_after: response.headers["Retry-After"]&.to_i,
+          http_status: response.status,
+          response_body: response.body
+        )
+      else
+        raise MaliPoPay::ApiError.new(
+          error_message(response),
+          http_status: response.status,
+          response_body: response.body
+        )
+      end
+    end
+
+    def error_message(response)
+      body = response.body
+      if body.is_a?(Hash)
+        body["message"] || body["error"] || "API error (#{response.status})"
+      else
+        "API error (#{response.status})"
+      end
+    end
+  end
+end

data/lib/malipopay/resources/account.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module MaliPoPay
+  module Resources
+    class Account
+      def initialize(http_client)
+        @http = http_client
+      end
+
+      # List all account transactions
+      # @param params [Hash] Query parameters (page, limit, dateFrom, dateTo, etc.)
+      # @return [Hash] Paginated list of account transactions
+      def transactions(params = {})
+        @http.get("/api/v1/account/allTransaction", params: params)
+      end
+
+      # Search account transactions
+      # @param params [Hash] Search parameters
+      # @return [Hash] Search results
+      def search_transactions(params = {})
+        @http.get("/api/v1/account/allTransaction", params: params)
+      end
+
+      # Get account reconciliation data
+      # @param params [Hash] Query parameters (dateFrom, dateTo, etc.)
+      # @return [Hash] Reconciliation data
+      def reconciliation(params = {})
+        @http.get("/api/v1/account/reconciliation", params: params)
+      end
+
+      # Get financial position report
+      # @param params [Hash] Query parameters
+      # @return [Hash] Financial position data
+      def financial_position(params = {})
+        @http.get("/api/v1/account/allTransaction", params: params.merge(report: "financial_position"))
+      end
+
+      # Get income statement
+      # @param params [Hash] Query parameters
+      # @return [Hash] Income statement data
+      def income_statement(params = {})
+        @http.get("/api/v1/account/allTransaction", params: params.merge(report: "income_statement"))
+      end
+
+      # Get general ledger
+      # @param params [Hash] Query parameters
+      # @return [Hash] General ledger data
+      def general_ledger(params = {})
+        @http.get("/api/v1/account/allTransaction", params: params.merge(report: "general_ledger"))
+      end
+
+      # Get trial balance
+      # @param params [Hash] Query parameters
+      # @return [Hash] Trial balance data
+      def trial_balance(params = {})
+        @http.get("/api/v1/account/allTransaction", params: params.merge(report: "trial_balance"))
+      end
+    end
+  end
+end

data/lib/malipopay/resources/customers.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module MaliPoPay
+  module Resources
+    class Customers
+      def initialize(http_client)
+        @http = http_client
+      end
+
+      # Create a new customer
+      # @param params [Hash] Customer parameters (name, phone, email, etc.)
+      # @return [Hash] Created customer
+      def create(params)
+        @http.post("/api/v1/customer", body: params)
+      end
+
+      # List all customers
+      # @param params [Hash] Query parameters (page, limit, etc.)
+      # @return [Hash] Paginated list of customers
+      def list(params = {})
+        @http.get("/api/v1/customer", params: params)
+      end
+
+      # Get a customer by ID
+      # @param id [String] Customer ID
+      # @return [Hash] Customer details
+      def get(id)
+        @http.get("/api/v1/customer/#{id}")
+      end
+
+      # Get a customer by customer number
+      # @param number [String] Customer number
+      # @return [Hash] Customer details
+      def get_by_number(number)
+        @http.get("/api/v1/customer/search", params: { customerNumber: number })
+      end
+
+      # Get a customer by phone number
+      # @param phone [String] Phone number
+      # @return [Hash] Customer details
+      def get_by_phone(phone)
+        @http.get("/api/v1/customer/search", params: { phone: phone })
+      end
+
+      # Search customers
+      # @param params [Hash] Search parameters
+      # @return [Hash] Search results
+      def search(params = {})
+        @http.get("/api/v1/customer/search", params: params)
+      end
+
+      # Verify a customer
+      # @param params [Hash] Verification parameters
+      # @return [Hash] Verification response
+      def verify_customer(params)
+        @http.post("/api/v1/customer/verify", body: params)
+      end
+    end
+  end
+end

data/lib/malipopay/resources/invoices.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module MaliPoPay
+  module Resources
+    class Invoices
+      def initialize(http_client)
+        @http = http_client
+      end
+
+      # Create a new invoice
+      # @param params [Hash] Invoice parameters
+      # @return [Hash] Created invoice
+      def create(params)
+        @http.post("/api/v1/invoice", body: params)
+      end
+
+      # List all invoices
+      # @param params [Hash] Query parameters (page, limit, status, etc.)
+      # @return [Hash] Paginated list of invoices
+      def list(params = {})
+        @http.get("/api/v1/invoice", params: params)
+      end
+
+      # Get an invoice by ID
+      # @param id [String] Invoice ID
+      # @return [Hash] Invoice details
+      def get(id)
+        @http.get("/api/v1/invoice/#{id}")
+      end
+
+      # Get an invoice by invoice number
+      # @param number [String] Invoice number
+      # @return [Hash] Invoice details
+      def get_by_number(number)
+        @http.get("/api/v1/invoice", params: { invoiceNumber: number })
+      end
+
+      # Update an existing invoice
+      # @param id [String] Invoice ID
+      # @param params [Hash] Updated invoice parameters
+      # @return [Hash] Updated invoice
+      def update(id, params)
+        @http.put("/api/v1/invoice/#{id}", body: params)
+      end
+
+      # Record a payment against an invoice
+      # @param params [Hash] Payment parameters (invoiceId, amount, reference, etc.)
+      # @return [Hash] Payment record response
+      def record_payment(params)
+        @http.post("/api/v1/invoice/record-payment", body: params)
+      end
+
+      # Approve a draft invoice
+      # @param params [Hash] Approval parameters (invoiceId, etc.)
+      # @return [Hash] Approval response
+      def approve_draft(params)
+        @http.post("/api/v1/invoice/approve-draft", body: params)
+      end
+    end
+  end
+end