lipwa 0.1.2 → 0.1.4

data/lib/lipwa/gateways/coop_bank.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "../gateway"
+require_relative "../gateways"
+require_relative "../capabilities/bank_transfer"
+require_relative "../capabilities/status_query"
+module Lipwa
+  module Gateways
+    class CoopBank < Lipwa::Gateway
+      include Lipwa::Capabilities::BankTransfer
+      include Lipwa::Capabilities::StatusQuery
+      BASE_URLS = { sandbox: "https://developer.co-opbank.co.ke:8243",
+                    production: "https://developer.co-opbank.co.ke:8243" }.freeze
+      TOKEN_URLS = BASE_URLS.transform_values { |url| "#{url}/token" }.freeze
+      PATHS = { internal: "/FundsTransfer/Internal/A2A/2.0.0", rtgs: "/FundsTransfer/External/A2A/2.0.0",
+                pesalink: "/FundsTransfer/External/A2M/2.0.0", bill_payment: "/BillPayment/PayBill/1.0.0",
+                balance: "/Enquiry/AccountBalance/1.0.0", statement: "/Enquiry/MiniStatement/1.0.0" }.freeze
+      STATUS_PATH = "/QueryStatus/v1.0.0/query"
+      setting :api_key
+      setting :api_secret
+      setting :client_id
+      setting :client_secret
+      setting :token_url
+      setting :clock
+
+      def status(message_reference:, idempotency_key: nil)
+        response = http.post(STATUS_PATH, body: { MessageReference: message_reference },
+                                          idempotency_key: idempotency_key)
+        build_status_query_response(response.body)
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      private
+
+      def build_http_adapter
+        config = self.config
+        api_key = config.api_key || config.client_id
+        api_secret = config.api_secret || config.client_secret
+        unless config.auth_strategy || (api_key && api_secret)
+          raise Lipwa::ConfigurationError,
+                "#{self.class} is missing api_key/api_secret — set them via .configure"
+        end
+
+        auth = config.auth_strategy || AuthStrategies::BearerToken.new(
+          Auth.new(client_id: api_key, client_secret: api_secret,
+                   token_url: config.token_url || TOKEN_URLS.fetch(config.env),
+                   clock: config.clock || -> { Time.now })
+        )
+        HttpAdapter.new(base_url: config.base_url || BASE_URLS.fetch(config.env),
+                        auth_strategy: auth,
+                        timeout: config.timeout || global_config.default_timeout,
+                        open_timeout: config.open_timeout, logger: config.logger || global_config.logger,
+                        adapter: global_config.adapter)
+      end
+
+      def bank_transfer_request(params, idempotency_key)
+        http.post(PATHS.fetch(params[:rail]), body: transfer_body(params), idempotency_key: idempotency_key)
+      end
+
+      def bank_balance_request(params, idempotency_key)
+        http.post(PATHS[:balance], body: inquiry_body(params), idempotency_key: idempotency_key)
+      end
+
+      def bank_statement_request(params, idempotency_key)
+        body = inquiry_body(params)
+        body[:StartDate] = params[:from_date].iso8601 if params[:from_date]
+        body[:EndDate] = params[:to_date].iso8601 if params[:to_date]
+        http.post(PATHS[:statement], body: body, idempotency_key: idempotency_key)
+      end
+
+      def status_query_request(params, idempotency_key)
+        http.post(STATUS_PATH, body: { MessageReference: params[:message_reference] },
+                               idempotency_key: idempotency_key)
+      end
+
+      def build_status_query_response(body)
+        code = body["MessageCode"]
+        Success(Lipwa::Response.new(success: code.to_s == "0",
+                                    provider_reference: body["MessageReference"]&.to_s,
+                                    message: body["MessageDescription"]&.to_s,
+                                    code: code&.to_s, raw: body))
+      end
+
+      def ensure_status_query_config_present!
+        # Co-op status queries use the gateway's normal OAuth credentials.
+      end
+
+      def transfer_body(params)
+        common = { MessageReference: params[:reference], CallBackUrl: params[:callback_url] }.compact
+        if params[:rail] == :bill_payment
+          return common.merge(AccountNumber: params[:source_account], BillerCode: params[:biller_code],
+                              BillAccountNumber: params[:destination_account], Amount: params[:amount].amount, Currency: params[:amount].currency, Narration: params[:narration] || params[:reference])
+        end
+
+        common.merge(Source: account_payload(params[:source_account], params),
+                     Destinations: [account_payload(params[:destination_account], params).merge(
+                       ReferenceNumber: params[:reference], BankCode: params[:destination_bank_code], BeneficiaryName: params[:destination_name]
+                     ).compact])
+      end
+
+      def account_payload(account, params)
+        { AccountNumber: account, Amount: params[:amount].amount, TransactionCurrency: params[:amount].currency,
+          Narration: params[:narration] || params[:reference] }
+      end
+
+      def inquiry_body(params)
+        { MessageReference: params[:message_reference] || SecureRandom.uuid, AccountNumber: params[:account_number] }
+      end
+    end
+  end
+end
+require_relative "coop_bank/auth"
+Lipwa::Gateways.register(:coop_bank, Lipwa::Gateways::CoopBank)

data/lib/lipwa/gateways/flutterwave.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+require_relative "../gateway"
+require_relative "../gateways"
+require_relative "../capabilities/purchase"
+require_relative "../capabilities/authorize"
+require_relative "../capabilities/capture"
+require_relative "../capabilities/void"
+
+module Lipwa
+  module Gateways
+    # Flutterwave v3 hosted payments and preauthorized card charges.
+    # rubocop:disable Metrics/ClassLength
+    class Flutterwave < Lipwa::Gateway
+      include Lipwa::Capabilities::Purchase
+      include Lipwa::Capabilities::Authorize
+      include Lipwa::Capabilities::Capture
+      include Lipwa::Capabilities::Void
+
+      BASE_URL = "https://api.flutterwave.com"
+      PAYMENTS_PATH = "/v3/payments"
+      CHARGES_PATH = "/v3/charges"
+
+      setting :secret_key
+      setting :encryption_key
+
+      private
+
+      def perform_purchase(params, idempotency_key)
+        response = http.post(PAYMENTS_PATH, body: hosted_payment_body(params), idempotency_key: idempotency_key)
+        build_flutterwave_response(response.body, fallback_reference: params[:reference])
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def perform_authorize(params, idempotency_key)
+        missing = %i[card_number cvv expiry_month expiry_year].reject { |key| params[key] }
+        return missing_card_failure(missing) unless missing.empty?
+
+        return missing_encryption_key_failure unless config.encryption_key
+
+        response = http.post(CHARGES_PATH, params: { type: "card" },
+                                           body: encrypted_card_body(params), idempotency_key: idempotency_key)
+        build_flutterwave_response(response.body, fallback_reference: params[:reference])
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def perform_capture(params, idempotency_key)
+        unless params[:amount]
+          return Failure(Lipwa::GatewayError.new("amount is required to capture a Flutterwave charge"))
+        end
+
+        response = http.post(charge_path(params[:authorization], "capture"),
+                             body: { amount: params[:amount].amount }, idempotency_key: idempotency_key)
+        build_flutterwave_response(response.body, fallback_reference: params[:authorization])
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def perform_void(params, idempotency_key)
+        response = http.post(charge_path(params[:authorization], "void"), body: {},
+                                                                          idempotency_key: idempotency_key)
+        build_flutterwave_response(response.body, fallback_reference: params[:authorization])
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      def hosted_payment_body(params)
+        address = params[:billing_address]
+        {
+          tx_ref: params[:reference], amount: params[:amount].amount, currency: params[:amount].currency,
+          redirect_url: params[:callback_url], payment_options: "card",
+          customer: {
+            email: address_value(address, :email_address),
+            phonenumber: address_value(address, :phone_number),
+            name: params[:fullname] || customer_name(address)
+          }.compact,
+          customizations: { title: params[:description], description: params[:description] }
+        }
+      end
+
+      # rubocop:enable Metrics/MethodLength
+      # rubocop:disable Metrics/AbcSize
+      def card_charge_body(params)
+        address = params[:billing_address]
+        {
+          card_number: params[:card_number], cvv: params[:cvv], expiry_month: params[:expiry_month],
+          expiry_year: params[:expiry_year], amount: params[:amount].amount,
+          currency: params[:amount].currency, email: address_value(address, :email_address),
+          fullname: params[:fullname] || customer_name(address),
+          phone_number: params[:phone_number] || address_value(address, :phone_number),
+          tx_ref: params[:reference], redirect_url: params[:callback_url],
+          preauthorize: true, usesecureauth: params.fetch(:usesecureauth, true)
+        }.compact
+      end
+
+      def encrypted_card_body(params)
+        cipher = OpenSSL::Cipher.new("des-ede3")
+        cipher.encrypt
+        cipher.key = config.encryption_key
+        encrypted = cipher.update(JSON.generate(card_charge_body(params))) + cipher.final
+        { client: Base64.strict_encode64(encrypted) }
+      end
+
+      # rubocop:enable Metrics/AbcSize
+      def customer_name(address)
+        name = [address_value(address, :first_name), address_value(address, :last_name)].compact.join(" ")
+        name unless name.empty?
+      end
+
+      def address_value(address, key) = address[key] || address[key.to_s]
+      def charge_path(reference, operation) = "#{CHARGES_PATH}/#{reference}/#{operation}"
+
+      def build_flutterwave_response(body, fallback_reference:)
+        data = body["data"].is_a?(Hash) ? body["data"] : {}
+        Success(Lipwa::Response.new(
+                  success: body["status"] == "success",
+                  provider_reference: (data["flw_ref"] || data["id"] || fallback_reference)&.to_s,
+                  message: body["message"] || data["processor_response"],
+                  code: body["status"]&.to_s,
+                  raw: body
+                ))
+      end
+
+      def missing_card_failure(missing)
+        Failure(Lipwa::GatewayError.new("missing #{missing.join(", ")}"))
+      end
+
+      def missing_encryption_key_failure
+        Failure(Lipwa::GatewayError.new("encryption_key is required to authorize a Flutterwave card"))
+      end
+
+      # rubocop:disable Metrics/AbcSize
+      def build_http_adapter
+        config = self.config
+        ensure_flutterwave_config_present!(config)
+        auth = config.auth_strategy || AuthStrategies::BearerToken.new(-> { config.secret_key })
+        HttpAdapter.new(base_url: config.base_url || BASE_URL, auth_strategy: auth,
+                        timeout: config.timeout || global_config.default_timeout,
+                        open_timeout: config.open_timeout, logger: config.logger || global_config.logger,
+                        adapter: global_config.adapter)
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def ensure_flutterwave_config_present!(config)
+        return if config.auth_strategy || config.secret_key
+
+        raise Lipwa::ConfigurationError, "#{self.class} is missing secret_key — set it via .configure"
+      end
+    end
+  end
+end
+
+# rubocop:enable Metrics/ClassLength
+Lipwa::Gateways.register(:flutterwave, Lipwa::Gateways::Flutterwave)

data/lib/lipwa/gateways/jenga/auth.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "time"
+require_relative "../../errors"
+
+module Lipwa
+  module Gateways
+    class Jenga
+      # Fetches and caches Jenga's merchant OAuth token.
+      class Auth
+        EXPIRY_BUFFER = 60
+
+        def initialize(api_key:, merchant_code:, consumer_secret:, token_url:, clock: -> { Time.now })
+          unless api_key && merchant_code && consumer_secret
+            raise Lipwa::ConfigurationError,
+                  "Jenga::Auth requires api_key, merchant_code, and consumer_secret"
+          end
+
+          @api_key = api_key
+          @merchant_code = merchant_code
+          @consumer_secret = consumer_secret
+          @token_url = token_url
+          @clock = clock
+          @mutex = Mutex.new
+        end
+
+        def initialize_copy(source)
+          super
+          @token = nil
+          @expires_at = nil
+          @mutex = Mutex.new
+        end
+
+        def inspect
+          "#<#{self.class}:0x#{object_id.to_s(16)}>"
+        end
+
+        def call
+          return @token if fresh?
+
+          @mutex.synchronize { refresh! unless fresh? }
+          @token
+        end
+
+        private
+
+        def fresh? = @token && @expires_at && @clock.call < @expires_at
+
+        def refresh!
+          response = Faraday.post(@token_url) do |request|
+            request.headers["Api-Key"] = @api_key
+            request.headers["Content-Type"] = "application/json"
+            request.body = JSON.generate(merchantCode: @merchant_code, consumerSecret: @consumer_secret)
+          end
+          body = JSON.parse(response.body)
+          unless response.success?
+            raise Lipwa::GatewayError.new("Jenga OAuth failed", code: response.status.to_s, raw: body)
+          end
+
+          @token = body.fetch("accessToken")
+          @expires_at = expiry_time(body.fetch("expiresIn", 900))
+        rescue Faraday::Error, JSON::ParserError, KeyError, ArgumentError => e
+          raise Lipwa::GatewayError.new("unexpected Jenga OAuth response: #{e.message}",
+                                        raw: defined?(body) ? body : nil)
+        end
+
+        def expiry_time(value)
+          expiry = value.is_a?(Numeric) || value.to_s.match?(/\A\d+\z/) ? @clock.call + value.to_i : Time.parse(value)
+          expiry - EXPIRY_BUFFER
+        end
+      end
+    end
+  end
+end

data/lib/lipwa/gateways/jenga.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "date"
+require "json"
+require_relative "../gateway"
+require_relative "../gateways"
+require_relative "../capabilities/bank_transfer"
+require_relative "../capabilities/disbursement"
+
+module Lipwa
+  module Gateways
+    # Equity/Finserve Jenga HQ gateway.
+    class Jenga < Lipwa::Gateway
+      include Lipwa::Capabilities::BankTransfer
+      include Lipwa::Capabilities::Disbursement
+
+      BASE_URLS = {
+        sandbox: "https://uat.finserve.africa/v3-apis",
+        production: "https://api.finserve.africa/v3-apis"
+      }.freeze
+      TOKEN_URLS = {
+        sandbox: "https://uat.finserve.africa/authentication/api/v3/authenticate/merchant",
+        production: "https://api.finserve.africa/authentication/api/v3/authenticate/merchant"
+      }.freeze
+      PATHS = {
+        internal: "/transaction-api/v3.0/remittance/internalBankTransfer",
+        pesalink: "/transaction-api/v3.0/remittance/pesalinkacc",
+        rtgs: "/transaction-api/v3.0/remittance/rtgs",
+        swift: "/transaction-api/v3.0/remittance/swift",
+        mobile: "/transaction-api/v3.0/remittance/sendmobile",
+        bill_payment: "/transaction-api/v3.0/bills/pay",
+        balance: "/account-api/v3.0/accounts/balances",
+        statement: "/account-api/v3.0/accounts/fullStatement",
+        forex: "/transaction-api/v3.0/foreignexchangerates"
+      }.freeze
+      TRANSFER_TYPES = {
+        internal: "EFT", pesalink: "PesaLink", rtgs: "RTGS", swift: "SWIFT"
+      }.freeze
+
+      setting :api_key
+      setting :merchant_code
+      setting :consumer_secret
+      setting :private_key
+      setting :source_account
+      setting :source_name
+      setting :country_code, default: "KE"
+      setting :partner_id
+      setting :token_url
+      setting :clock
+
+      def forex_rates(currency_code:, amount:, to_currency:, account_number: nil, country_code: nil, idempotency_key: nil)
+        body = {
+          accountNumber: account_number,
+          countryCode: country_code || config.country_code,
+          currencyCode: currency_code,
+          amount: format_amount(amount),
+          toCurrency: to_currency
+        }.compact
+        response = http.post(PATHS[:forex], body: body, idempotency_key: idempotency_key)
+        build_jenga_response(response.body)
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      private
+
+      def build_http_adapter
+        config = self.config
+        ensure_jenga_config_present!(config)
+        auth_strategy = config.auth_strategy || AuthStrategies::Jenga.new(
+          token_provider: Auth.new(
+            api_key: config.api_key,
+            merchant_code: config.merchant_code,
+            consumer_secret: config.consumer_secret,
+            token_url: config.token_url || TOKEN_URLS.fetch(config.env),
+            clock: config.clock || -> { Time.now }
+          ),
+          private_key: config.private_key,
+          signature_payload: method(:signature_payload)
+        )
+
+        HttpAdapter.new(
+          base_url: config.base_url || BASE_URLS.fetch(config.env),
+          auth_strategy: auth_strategy,
+          timeout: config.timeout || global_config.default_timeout,
+          open_timeout: config.open_timeout,
+          logger: config.logger || global_config.logger,
+          adapter: global_config.adapter
+        )
+      end
+
+      def ensure_jenga_config_present!(config)
+        required = %i[source_account source_name]
+        required.concat(%i[api_key merchant_code consumer_secret private_key]) unless config.auth_strategy
+        missing = required.reject { |name| config.public_send(name) }
+        return if missing.empty?
+
+        raise Lipwa::ConfigurationError,
+              "#{self.class} is missing #{missing.join("/")} — set them via .configure"
+      end
+
+      def bank_transfer_request(params, idempotency_key)
+        path = PATHS.fetch(params[:rail])
+        body = params[:rail] == :bill_payment ? bill_payment_body(params) : bank_transfer_body(params)
+        http.post(path, body: body, idempotency_key: idempotency_key)
+      end
+
+      def bank_balance_request(params, idempotency_key)
+        country = config.country_code
+        http.get("#{PATHS[:balance]}/#{country}/#{params[:account_number]}", idempotency_key: idempotency_key)
+      end
+
+      def bank_statement_request(params, idempotency_key)
+        date = request_date
+        body = {
+          countryCode: config.country_code,
+          accountNumber: params[:account_number],
+          fromDate: (params[:from_date] || date).iso8601,
+          toDate: (params[:to_date] || date).iso8601
+        }
+        http.post(PATHS[:statement], body: body, idempotency_key: idempotency_key)
+      end
+
+      def bank_transfer_body(params)
+        {
+          source: source_payload(params[:source_account]),
+          destination: {
+            type: "bank",
+            countryCode: config.country_code,
+            name: params[:destination_name],
+            accountNumber: params[:destination_account],
+            bankCode: params[:destination_bank_code]
+          }.compact,
+          transfer: transfer_payload(params, TRANSFER_TYPES.fetch(params[:rail]))
+        }
+      end
+
+      def bill_payment_body(params)
+        {
+          biller: {
+            billerCode: params[:biller_code],
+            countryCode: config.country_code
+          },
+          bill: {
+            reference: params[:destination_account],
+            amount: format_amount(params[:amount].amount),
+            currency: params[:amount].currency
+          },
+          payer: {
+            name: config.source_name,
+            accountNumber: params[:source_account],
+            reference: params[:reference]
+          },
+          partnerId: config.partner_id || config.merchant_code
+        }
+      end
+
+      def transfer_payload(params, type)
+        {
+          type: type,
+          amount: format_amount(params[:amount].amount),
+          currencyCode: params[:amount].currency,
+          reference: params[:reference],
+          date: request_date.iso8601,
+          description: params[:narration] || params[:reference],
+          callbackUrl: params[:callback_url]
+        }.compact
+      end
+
+      # Provider-specific implementation behind the shared Disbursement API.
+      def perform_disburse(params, idempotency_key)
+        response = http.post(PATHS[:mobile], body: mobile_money_body(params), idempotency_key: idempotency_key)
+        build_jenga_response(response.body)
+      rescue Lipwa::GatewayError => e
+        Failure(e)
+      end
+
+      def ensure_disbursement_config_present!
+        ensure_jenga_config_present!(config)
+      end
+
+      def mobile_money_body(params)
+        reference = params[:account_reference] || params[:occasion] || SecureRandom.uuid
+        {
+          source: source_payload(config.source_account),
+          destination: {
+            type: "mobile",
+            countryCode: config.country_code,
+            name: params[:party_b],
+            mobileNumber: params[:party_b],
+            walletName: "Mpesa"
+          },
+          transfer: {
+            type: "MobileWallet",
+            amount: format_amount(params[:amount].amount),
+            currencyCode: params[:amount].currency,
+            reference: reference,
+            date: request_date.iso8601,
+            description: params[:remarks],
+            callbackUrl: params[:result_url]
+          }
+        }
+      end
+
+      def source_payload(account)
+        {
+          countryCode: config.country_code,
+          name: config.source_name,
+          accountNumber: account
+        }
+      end
+
+      def signature_payload(env)
+        body = env.body.to_s.empty? ? {} : JSON.parse(env.body)
+        path = env.url.path
+        case path
+        when /sendmobile\z/
+          join_fields(body, %w[transfer.amount transfer.currencyCode transfer.reference source.accountNumber])
+        when /internalBankTransfer\z/
+          join_fields(body, %w[source.accountNumber transfer.amount transfer.currencyCode transfer.reference])
+        when /pesalinkacc\z/
+          join_fields(body,
+                      %w[transfer.amount transfer.currencyCode transfer.reference destination.name
+                         source.accountNumber])
+        when /(?:rtgs|swift)\z/
+          join_fields(body,
+                      %w[transfer.reference transfer.date source.accountNumber destination.accountNumber
+                         transfer.amount])
+        when %r{bills/pay\z}
+          join_fields(body, %w[biller.billerCode bill.amount payer.reference partnerId])
+        when /fullStatement\z/
+          join_fields(body, %w[accountNumber countryCode toDate])
+        when /foreignexchangerates\z/
+          join_fields(body, %w[countryCode currencyCode amount toCurrency])
+        when %r{accounts/balances/([^/]+)/([^/]+)\z}
+          "#{Regexp.last_match(1)}#{Regexp.last_match(2)}"
+        else
+          raise Lipwa::ConfigurationError, "no Jenga signature formula for #{path}"
+        end
+      end
+
+      def join_fields(body, fields)
+        fields.map do |field|
+          field.split(".").reduce(body) { |value, key| value.fetch(key) }
+        end.join
+      rescue KeyError => e
+        raise Lipwa::ConfigurationError, "missing Jenga signature field: #{e.key}"
+      end
+
+      def build_bank_response(body) = build_jenga_response(body)
+
+      def build_jenga_response(body)
+        data = body["data"].is_a?(Hash) ? body["data"] : {}
+        code = body["code"] || body["statusCode"] || data["code"]
+        reference = body["reference"] || body["transactionId"] ||
+                    data["reference"] || data["transactionId"]
+        message = body["message"] || body["description"] || data["message"]
+        success = body["status"] != false && (code.nil? || %w[0 00 200 201 SUCCESS Success].include?(code.to_s))
+        Success(Lipwa::Response.new(
+                  success: success,
+                  provider_reference: reference&.to_s,
+                  message: message&.to_s,
+                  code: code&.to_s,
+                  raw: body
+                ))
+      end
+
+      def request_date
+        value = config.clock&.call || Date.today
+        value.respond_to?(:to_date) ? value.to_date : value
+      end
+
+      def format_amount(value)
+        format("%.2f", value)
+      end
+    end
+  end
+end
+
+require_relative "jenga/auth"
+Lipwa::Gateways.register(:jenga, Lipwa::Gateways::Jenga)