lipwa 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8c3c39d3377082721898d3509aad157a7736fe63907624e3af5c4a55268f9329
+  data.tar.gz: 1a6d082d6196adb81e1ee610609663156dbf3f35e4c2f82a5f7ab54b66797a7f
+SHA512:
+  metadata.gz: c5fdb5ec67a5b767ef60d0b709540a666cbede85e80d12880e8eaf956a09b57ae0088727ad35bff6c7c5b0ef65c5791bd290b146b093bf65c191c2b011b27a39
+  data.tar.gz: 4e078b48e6ca4b10cf76bcff8fc1c2a5d8e5c0c0e1534dd56131b282dfb8b23c0f560adf77af02498a16d55da4c33cd636ccf31a70440248ad6673962a4dc76d

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+## [0.1.1]
+
+- Add `Lipwa::HttpAdapter`, a Faraday-based HTTP wrapper
+- Add `Lipwa::Gateways` container/registry for gateway implementations
+- Wire dry-rb dependencies into the gemspec and `Lipwa.configure`
+- Add M-Pesa OAuth2 client-credentials token handling
+- Implement the `StkPush` capability
+- Implement the `C2B` capability (validation/confirmation)
+- Implement the `WebhookHandling` capability and `Lipwa::Webhook`
+- Add VCR/WebMock cassettes for M-Pesa sandbox flows
+- Implement the `Disbursement` capability (B2C/B2B)
+- Implement the `StatusQuery` capability
+
+## [0.1.0] - 2026-08-28
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"lipwa" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["mcpaul2058@gmail.com"](mailto:"mcpaul2058@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Paul Oguda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,288 @@
+# Lipwa
+
+Lipwa is a unified Ruby gem for accepting and disbursing payments across
+African payment providers — mobile money, bank APIs, and (eventually) card
+rails — behind one consistent, capability-based interface. It currently
+ships a full integration with Safaricom's **M-Pesa Daraja API**: STK Push,
+C2B, B2C/B2B disbursements, and inbound webhook handling.
+
+Every gateway call returns a `Dry::Monads::Result`
+(`Success(Lipwa::Response)` / `Failure(Lipwa::Error)`) instead of raising —
+see [Error handling](#error-handling) below. Only genuine programmer
+mistakes (bad config, calling a capability the gateway doesn't support) are
+raised as exceptions.
+
+## Installation
+
+Install the gem and add it to the application's Gemfile by executing:
+
+```bash
+bundle add lipwa
+```
+
+If bundler is not being used to manage dependencies, install the gem by
+executing:
+
+```bash
+gem install lipwa
+```
+
+## Configuration
+
+Set gem-wide defaults once (logger, default timeout, Faraday adapter — all
+optional):
+
+```ruby
+Lipwa.configure do |config|
+  config.logger = Rails.logger
+  config.default_timeout = 10
+end
+```
+
+Then configure each gateway you use. For M-Pesa:
+
+```ruby
+Lipwa::Gateways::Mpesa.configure do |c|
+  c.env = :sandbox # or :production
+  c.consumer_key = ENV["MPESA_CONSUMER_KEY"]
+  c.consumer_secret = ENV["MPESA_CONSUMER_SECRET"]
+  c.shortcode = ENV["MPESA_SHORTCODE"]
+  c.passkey = ENV["MPESA_PASSKEY"] # STK Push only
+
+  # B2C/B2B disbursements only:
+  c.initiator_name = ENV["MPESA_INITIATOR_NAME"]
+  c.initiator_password = ENV["MPESA_INITIATOR_PASSWORD"]
+  c.security_credential_cert = File.read(ENV["MPESA_CERT_PATH"])
+end
+```
+
+`consumer_key`/`consumer_secret` authenticate every Daraja call (OAuth2
+client-credentials, cached and auto-refreshed). `shortcode`/`passkey` are
+only needed for STK Push and C2B. `initiator_name`/`initiator_password`/
+`security_credential_cert` are only needed if you call `#disburse` — see
+[Disbursement](#disbursement-b2c--b2b) for what the cert is and where to
+get it. Configuring only what you actually use is fine; each capability
+raises `Lipwa::ConfigurationError` at call time if something it needs is
+missing, not at load time.
+
+Fetch a configured gateway by name instead of referencing the class
+directly:
+
+```ruby
+Lipwa.gateway(:mpesa).stk_push(...)
+```
+
+## Usage
+
+### STK Push (Lipa Na M-Pesa Online)
+
+Pushes a payment prompt to the payer's phone. The actual result of the
+payment arrives later at `callback_url` — a successful call here only
+confirms Daraja *accepted* the request, not that the customer paid.
+
+```ruby
+result = Lipwa.gateway(:mpesa).stk_push(
+  amount: Lipwa::Money.new(amount: 100, currency: "KES"), # 100 = 1.00 KES, minor units
+  phone_number: "254712345678",
+  account_reference: "ORDER-123",
+  callback_url: "https://example.com/webhooks/mpesa/stk"
+)
+
+result.either(
+  ->(response) { response.provider_reference }, # CheckoutRequestID
+  ->(error) { logger.error(error.message) }
+)
+```
+
+### C2B (Customer to Business)
+
+Registers the validation/confirmation webhook URLs Daraja calls when a
+customer pays your paybill/till directly (outside STK Push), and — sandbox
+only — simulates such a payment so you can exercise those URLs without a
+real transaction.
+
+```ruby
+Lipwa.gateway(:mpesa).register_urls(
+  validation_url: "https://example.com/webhooks/mpesa/validate",
+  confirmation_url: "https://example.com/webhooks/mpesa/confirm"
+)
+
+# Sandbox only:
+Lipwa.gateway(:mpesa).simulate(
+  amount: Lipwa::Money.new(amount: 100, currency: "KES"),
+  phone_number: "254712345678",
+  bill_ref_number: "ORDER-123"
+)
+```
+
+### Disbursement (B2C / B2B)
+
+`#disburse` sends money out from your shortcode — to a customer's phone
+(B2C: salaries, promotions, business payments) or to another business
+(B2B: paybill/till settlement) — driven by `command_id` rather than two
+separate methods:
+
+```ruby
+# B2C — pay out to a customer's phone
+result = Lipwa.gateway(:mpesa).disburse(
+  command_id: "SalaryPayment", # or "BusinessPayment" / "PromotionPayment"
+  amount: Lipwa::Money.new(amount: 5_000_00, currency: "KES"),
+  party_b: "254712345678", # payee MSISDN
+  remarks: "August salary",
+  result_url: "https://example.com/webhooks/mpesa/b2c/result",
+  queue_timeout_url: "https://example.com/webhooks/mpesa/b2c/timeout",
+  occasion: "August payroll"
+)
+
+# B2B — settle with another business shortcode
+result = Lipwa.gateway(:mpesa).disburse(
+  command_id: "BusinessPayBill", # or "BusinessBuyGoods" / "MerchantToMerchantTransfer"
+  amount: Lipwa::Money.new(amount: 10_000_00, currency: "KES"),
+  party_b: "600000", # payee business shortcode
+  remarks: "Supplier settlement",
+  result_url: "https://example.com/webhooks/mpesa/b2b/result",
+  queue_timeout_url: "https://example.com/webhooks/mpesa/b2b/timeout",
+  account_reference: "INV-2026-08-001" # required for B2B command IDs
+)
+```
+
+Like STK Push, `#disburse` only confirms Daraja *accepted* the request
+(`ConversationID`) — the outcome (success or failure of the actual
+payout) arrives later at `result_url`.
+
+**About `security_credential_cert`**: Daraja requires every B2C/B2B
+request to carry a `SecurityCredential` — your initiator password,
+RSA-encrypted with Safaricom's public certificate. Lipwa does this
+encryption for you (see `Lipwa::Gateways::Mpesa::SecurityCredential`); you
+just need to supply the certificate itself as PEM/DER content via
+`security_credential_cert`. Download it from the Daraja developer
+portal — the **Test Credentials** page for sandbox, or your app's
+production certificate for production — since sandbox and production use
+different certificates and mixing them up causes every B2C/B2B request to
+fail. Don't hardcode certificate content in source; load it from a file or
+secret store, e.g. `c.security_credential_cert = File.read("certs/mpesa_production.cer")`.
+
+### Refund
+
+`#refund` reverses a completed M-Pesa transaction by its `TransactionID`
+(Daraja's Transaction Reversal API):
+
+```ruby
+result = Lipwa.gateway(:mpesa).refund(
+  transaction_id: "OEI2AK4Q16",
+  amount: Lipwa::Money.new(amount: 100_00, currency: "KES"),
+  remarks: "Missing item",
+  result_url: "https://example.com/webhooks/mpesa/reversal/result",
+  queue_timeout_url: "https://example.com/webhooks/mpesa/reversal/timeout",
+  occasion: "Customer complaint"
+)
+```
+
+Like `#disburse`, `#refund` only confirms Daraja *accepted* the reversal
+request — the outcome arrives later at `result_url`. It requires the same
+`security_credential_cert` as `#disburse` — see
+[Disbursement](#disbursement-b2c--b2b) for what the cert is and where to
+get it.
+
+### Webhook handling
+
+Daraja delivers STK Push results and C2B validation/confirmation as
+inbound HTTP callbacks. Parse and (for M-Pesa) verify them with
+`Lipwa::Webhook`:
+
+```ruby
+# in your webhook controller
+result = Lipwa::Webhook.parse_webhook(provider: :mpesa, body: request.body.read, headers: request.headers)
+
+result.either(
+  lambda do |event|
+    if event.verify_signature(source_ip: request.remote_ip)
+      # event.event_type   => :stk_callback or :c2b
+      # event.success?     => whether the STK push succeeded (always true for C2B —
+      #                       C2B callbacks only fire for an already-completed payment)
+      # event.provider_reference => CheckoutRequestID (STK) or TransID (C2B)
+      handle(event)
+    else
+      head :forbidden
+    end
+  end,
+  ->(error) { logger.error(error.message) }
+)
+```
+
+M-Pesa doesn't cryptographically sign callbacks, so `verify_signature`
+checks the request's source IP against Safaricom's published callback IP
+ranges instead — always call it before trusting a callback's contents.
+
+### `Lipwa::Money`
+
+Amounts are always a `Lipwa::Money` — an immutable value object storing
+minor currency units (e.g. `100` = KES 1.00) plus an ISO 4217 currency
+code (defaults to `"KES"`):
+
+```ruby
+Lipwa::Money.new(amount: 100, currency: "KES")
+```
+
+## Error handling
+
+Gateway methods (`#stk_push`, `#register_urls`, `#simulate`, `#disburse`)
+never raise for expected failure modes — they return a
+`Dry::Monads::Result`:
+
+- `Success(Lipwa::Response)` — `#success?`, `#provider_reference`,
+  `#message`, `#code`, `#raw` (the parsed provider response). Note a
+  `Success` can still wrap `response.success? == false` — Daraja
+  synchronous validation errors (bad shortcode, malformed request) come
+  back as a normal 200 response with a non-zero `ResponseCode`.
+- `Failure(Lipwa::ValidationError)` — your params failed contract
+  validation before any network call was made.
+- `Failure(Lipwa::GatewayError)` — the HTTP call itself failed (timeout,
+  connection error) or the provider returned an HTTP error status.
+
+`Lipwa::ConfigurationError` and `Lipwa::UnsupportedCapabilityError` are
+raised, not wrapped — they represent programmer/ops mistakes (missing
+credentials, calling a capability a gateway doesn't include) that should
+fail loudly at call time rather than be routed through error-handling
+code.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `rake test` to run the tests. You can also run `bin/console` for
+an interactive prompt that will allow you to experiment.
+
+Tests run against hand-authored VCR cassettes
+(`test/fixtures/vcr_cassettes/mpesa/`) with fake sandbox credentials —
+they never hit Safaricom's real sandbox, so no network access or real
+credentials are needed to run the suite.
+
+`examples/rails_api` is a small Rails API app that exercises every
+capability against a real (sandbox) Daraja account — STK Push, C2B,
+disbursement, refund, and inbound webhooks — useful both for evaluating
+the gem and for manually smoke-testing changes. It's excluded from the
+released gem package. See its own README for setup.
+
+To install this gem onto your local machine, run `bundle exec rake
+install`. To release a new version, update the version number in
+`version.rb`, and then run `bundle exec rake release`, which will create a
+git tag for the version, push git commits and the created tag, and push
+the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/kamalogudah/lipwa. This project is intended to be a
+safe, welcoming space for collaboration, and contributors are expected to
+adhere to the [code of conduct](https://github.com/kamalogudah/lipwa/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Lipwa project's codebases, issue trackers,
+chat rooms and mailing lists is expected to follow the
+[code of conduct](https://github.com/kamalogudah/lipwa/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/lipwa/auth_strategies/base.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Lipwa
+  module AuthStrategies
+    # Interface every auth strategy implements. An HttpAdapter is handed
+    # one of these and calls #apply on every outgoing request, letting
+    # the strategy mutate headers (bearer token, HMAC/RSA signature,
+    # timestamp, whatever the provider needs) without HttpAdapter knowing
+    # which kind of auth it's dealing with.
+    class Base
+      # env is a Faraday::Env — mutate env.request_headers / env.body
+      # in place. Must be implemented by subclasses.
+      def apply(env)
+        raise NotImplementedError, "#{self.class} must implement #apply"
+      end
+    end
+  end
+end

data/lib/lipwa/auth_strategies/bearer_token.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Lipwa
+  module AuthStrategies
+    # Sets `Authorization: Bearer <token>` on every request. Covers the
+    # OAuth2 client-credentials providers (M-Pesa Daraja, Co-op Bank):
+    # each gateway supplies its own token source — typically an object
+    # that fetches and caches a token from the provider's OAuth endpoint
+    # and refreshes it once expired — as `token_provider`.
+    #
+    # token_provider must respond to #call and return a token String.
+    class BearerToken < Base
+      def initialize(token_provider)
+        raise ArgumentError, "token_provider must respond to #call" unless token_provider.respond_to?(:call)
+
+        super()
+        @token_provider = token_provider
+      end
+
+      def apply(env)
+        env.request_headers["Authorization"] = "Bearer #{@token_provider.call}"
+      end
+    end
+  end
+end

data/lib/lipwa/auth_strategies/none.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Lipwa
+  module AuthStrategies
+    # Default strategy: adds nothing. Used for endpoints that need no
+    # auth (e.g. some public sandbox calls) or as a placeholder while a
+    # gateway is configured.
+    class None < Base
+      def apply(env); end
+    end
+  end
+end

data/lib/lipwa/auth_strategies.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "auth_strategies/base"
+require_relative "auth_strategies/none"
+require_relative "auth_strategies/bearer_token"

data/lib/lipwa/capabilities/c2b.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require_relative "../capability"
+require_relative "../contracts/c2b_register_urls_contract"
+require_relative "../contracts/c2b_simulate_contract"
+
+module Lipwa
+  module Capabilities
+    # Customer To Business (C2B): registers the validation/confirmation
+    # webhook URLs Daraja calls when a customer pays a paybill/till
+    # directly (outside STK Push), and — sandbox only — simulates such
+    # a payment for testing. The actual payment notification arrives
+    # later at the registered confirmation URL; these calls only manage
+    # that registration and drive the sandbox simulator.
+    module C2B
+      extend Lipwa::Capability
+      include Dry::Monads[:result]
+      self.capability_name = :c2b
+
+      REGISTER_URLS_PATH = "/mpesa/c2b/v1/registerurl"
+      SIMULATE_PATH = "/mpesa/c2b/v1/simulate"
+
+      REGISTER_URLS_CONTRACT = Lipwa::Contracts::C2bRegisterUrlsContract.new
+      SIMULATE_CONTRACT = Lipwa::Contracts::C2bSimulateContract.new
+
+      def register_urls(validation_url:, confirmation_url:, response_type: "Completed")
+        validation = REGISTER_URLS_CONTRACT.call(
+          validation_url: validation_url,
+          confirmation_url: confirmation_url,
+          response_type: response_type
+        )
+        return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
+
+        perform_register_urls(validation.to_h)
+      end
+
+      # Sandbox-only: triggers a simulated C2B payment so the
+      # registered validation/confirmation URLs can be exercised
+      # without a real customer transaction.
+      def simulate(amount:, phone_number:, bill_ref_number:, command_id: "CustomerPayBillOnline")
+        validation = SIMULATE_CONTRACT.call(
+          amount: amount,
+          phone_number: phone_number,
+          bill_ref_number: bill_ref_number,
+          command_id: command_id
+        )
+        return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
+
+        perform_simulate(validation.to_h)
+      end
+
+      private
+
+      def perform_register_urls(params)
+        response = http.post(REGISTER_URLS_PATH, body: register_urls_body(params))
+
+        build_c2b_response(response.body)
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def register_urls_body(params)
+        {
+          ShortCode: self.class.config.shortcode,
+          ResponseType: params[:response_type],
+          ConfirmationURL: params[:confirmation_url],
+          ValidationURL: params[:validation_url]
+        }
+      end
+
+      def perform_simulate(params)
+        response = http.post(SIMULATE_PATH, body: simulate_body(params))
+
+        build_c2b_response(response.body)
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def simulate_body(params)
+        {
+          ShortCode: self.class.config.shortcode,
+          CommandID: params[:command_id],
+          Amount: params[:amount].amount,
+          Msisdn: params[:phone_number],
+          BillRefNumber: params[:bill_ref_number]
+        }
+      end
+
+      def build_c2b_response(body)
+        Success(Lipwa::Response.new(
+                  success: body["ResponseCode"] == "0",
+                  provider_reference: body["ConversationID"] || body["OriginatorConversationID"] ||
+                    body["OriginatorCoversationID"],
+                  message: body["ResponseDescription"] || body["errorMessage"],
+                  code: (body["ResponseCode"] || body["errorCode"])&.to_s,
+                  raw: body
+                ))
+      end
+    end
+  end
+end

data/lib/lipwa/capabilities/disbursement.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require_relative "../capability"
+require_relative "../contracts/disbursement_contract"
+
+module Lipwa
+  module Capabilities
+    # Disburses funds from the gateway's shortcode to a customer (B2C —
+    # salary/promotion/business payments to an MSISDN) or another
+    # business (B2B — paybill/till settlement), driven by `command_id`
+    # rather than two separate methods, per the target #disburse API.
+    # Unlike StkPush/C2B, Daraja requires a SecurityCredential — the
+    # initiator password RSA-encrypted with Safaricom's public
+    # certificate — computed fresh on every call since PKCS#1 padding is
+    # randomized.
+    module Disbursement
+      extend Lipwa::Capability
+      include Dry::Monads[:result]
+      self.capability_name = :disbursement
+
+      B2C_PATH = "/mpesa/b2c/v1/paymentrequest"
+      B2B_PATH = "/mpesa/b2b/v1/paymentrequest"
+      B2C_COMMAND_IDS = Lipwa::Contracts::DisbursementContract::B2C_COMMAND_IDS
+      B2B_COMMAND_IDS = Lipwa::Contracts::DisbursementContract::B2B_COMMAND_IDS
+
+      CONTRACT = Lipwa::Contracts::DisbursementContract.new
+
+      # rubocop:disable Metrics/ParameterLists
+      def disburse(command_id:, amount:, party_b:, remarks:, result_url:, queue_timeout_url:, occasion: nil,
+                   account_reference: nil)
+        validate_and_disburse(
+          command_id: command_id, amount: amount, party_b: party_b, remarks: remarks,
+          result_url: result_url, queue_timeout_url: queue_timeout_url,
+          occasion: occasion, account_reference: account_reference
+        )
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      private
+
+      def validate_and_disburse(args)
+        validation = CONTRACT.call(args)
+        return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
+
+        perform_disburse(validation.to_h)
+      end
+
+      def perform_disburse(params)
+        ensure_disbursement_config_present!
+        path = B2C_COMMAND_IDS.include?(params[:command_id]) ? B2C_PATH : B2B_PATH
+
+        response = http.post(path, body: disbursement_body(params))
+
+        build_disbursement_response(response.body)
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def disbursement_body(params)
+        if B2C_COMMAND_IDS.include?(params[:command_id])
+          b2c_body(params)
+        else
+          b2b_body(params)
+        end
+      end
+
+      def b2c_body(params)
+        {
+          InitiatorName: self.class.config.initiator_name,
+          SecurityCredential: security_credential,
+          CommandID: params[:command_id],
+          PartyA: self.class.config.shortcode,
+          PartyB: params[:party_b],
+          Occasion: params[:occasion]
+        }.merge(shared_disbursement_fields(params))
+      end
+
+      def b2b_body(params)
+        {
+          Initiator: self.class.config.initiator_name,
+          SecurityCredential: security_credential,
+          CommandID: params[:command_id],
+          SenderIdentifierType: "4",
+          RecieverIdentifierType: "4",
+          PartyA: self.class.config.shortcode,
+          PartyB: params[:party_b],
+          AccountReference: params[:account_reference]
+        }.merge(shared_disbursement_fields(params))
+      end
+
+      def shared_disbursement_fields(params)
+        {
+          Amount: params[:amount].amount,
+          Remarks: params[:remarks],
+          QueueTimeOutURL: params[:queue_timeout_url],
+          ResultURL: params[:result_url]
+        }
+      end
+
+      def security_credential
+        Lipwa::Gateways::Mpesa::SecurityCredential.encrypt(
+          self.class.config.initiator_password,
+          cert: self.class.config.security_credential_cert
+        )
+      end
+
+      def build_disbursement_response(body)
+        Success(Lipwa::Response.new(
+                  success: body["ResponseCode"] == "0",
+                  provider_reference: body["ConversationID"] || body["OriginatorConversationID"] ||
+                    body["OriginatorCoversationID"],
+                  message: body["ResponseDescription"] || body["errorMessage"],
+                  code: (body["ResponseCode"] || body["errorCode"])&.to_s,
+                  raw: body
+                ))
+      end
+
+      def ensure_disbursement_config_present!
+        config = self.class.config
+        return if config.initiator_name && config.initiator_password && config.security_credential_cert
+
+        raise Lipwa::ConfigurationError,
+              "#{self.class} is missing initiator_name/initiator_password/security_credential_cert " \
+              "— set them via .configure to use #disburse"
+      end
+    end
+  end
+end