rma-payment-gateway 1.0.0

data/lib/rma/payment/gateway/client.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Rma
+  module Payment
+    module Gateway
+      # Client class for RMA Payment Gateway.
+      # Handles all communication with the RMA Payment Gateway API.
+      #
+      # @example
+      #   client = Rma::Payment::Gateway::Client.new
+      #   client.authorization
+      #   client.account_inquiry
+      #   client.debit_request
+      #
+      # @param config [Rma::Payment::Gateway::Configuration] Configuration instance
+      class Client
+        attr_reader :config, :access_token, :private_key
+
+        def initialize(config = nil)
+          @config = config || Rma::Payment::Gateway.configuration
+          validate_configuration!
+        end
+
+        # Authorization methods
+        def authorization
+          @authorization ||= Authorization.new(self)
+        end
+
+        # Account Inquiry methods
+        def account_inquiry
+          @account_inquiry ||= AccountInquiry.new(self)
+        end
+
+        # Debit Request methods
+        def debit_request
+          @debit_request ||= DebitRequest.new(self)
+        end
+
+        # HTTP request methods
+        def post(body: {}, headers: {})
+          request(:post, body: body, headers: headers)
+        end
+
+        def get(headers: {})
+          request(:get, headers: headers)
+        end
+
+        private
+
+        def validate_configuration!
+          raise ConfigurationError, "Configuration is required" if config.nil?
+          return if config.valid?
+
+          raise ConfigurationError, "Missing required configuration fields: #{config.missing_fields.join(", ")}"
+        end
+
+        def request(method, body: {}, headers: {})
+          response = connection.send(method) do |req|
+            req.url "/BFSSecure/nvpapi"
+            req.headers = build_headers(headers)
+            req.body = body.to_query if method == :post && !body.empty?
+          end
+
+          handle_response(response)
+        rescue Faraday::Error => e
+          raise NetworkError, "Network error: #{e.message}"
+        end
+
+        def connection
+          @connection ||= Faraday.new(url: config.base_url) do |conn|
+            conn.request :url_encoded
+            conn.response :json, content_type: /\bjson$/
+            conn.adapter Faraday.default_adapter
+            conn.options.timeout = config.timeout
+            conn.options.open_timeout = config.open_timeout
+          end
+        end
+
+        def build_headers(custom_headers = {})
+          headers = { "Content-Type" => "application/x-www-form-urlencoded" }
+          headers.merge(custom_headers)
+        end
+
+        def handle_response(response)
+          case response.status
+          when 200..299
+            response.body
+          when 400..499
+            handle_client_error(response)
+          when 500..599
+            handle_server_error(response)
+          else
+            raise APIError, "Unexpected response status: #{response.status}"
+          end
+        end
+
+        def handle_client_error(response)
+          body = response.body || {}
+          error_message = body["result"]["bfs_responseDesc"] || "Client error"
+
+          raise InvalidParameterError.new(
+            error_message,
+            response_code: body["result"]["bfs_responseCode"],
+            response_detail: body["result"]["bfs_responseDesc"]
+          )
+        end
+
+        def handle_server_error(response)
+          body = response.body || {}
+          error_message = body["result"]["bfs_responseDesc"] || "Server error"
+
+          raise APIError.new(
+            error_message,
+            response_code: body["result"]["bfs_responseCode"],
+            response_description: body["result"]["bfs_responseDesc"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rma/payment/gateway/configuration.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "dotenv/load" # Load environment variables
+
+module Rma
+  module Payment
+    module Gateway
+      # Configuration class for RMA Payment Gateway.
+      # Handles all configuration options required for the RMA Payment Gateway client.
+      #
+      # @example
+      #   config = Rma::Payment::Gateway::Configuration.new
+      #   config.base_url = 'https://api.example.com'
+      #   config.rsa_key_path = '/path/to/rsa_key.pem'
+      #   config.beneficiary_id = 'YOUR_BENEFICIARY_ID'
+      class Configuration
+        attr_accessor :base_url, :rsa_key_path, :beneficiary_id, :payment_description, :timeout, :open_timeout
+
+        def initialize
+          @base_url = ENV["RMA_BASE_URL"]
+          @rsa_key_path = ENV["RMA_RSA_KEY_PATH"]
+          @beneficiary_id = ENV["RMA_BENEFICIARY_ID"]
+          @payment_description = ENV["RMA_PAYMENT_DESCRIPTION"]
+          @timeout = 30
+          @open_timeout = 10
+        end
+
+        def valid?
+          required_fields.all? { |field| !send(field).nil? && !send(field).to_s.empty? }
+        end
+
+        def required_fields
+          %i[base_url rsa_key_path beneficiary_id payment_description]
+        end
+
+        def missing_fields
+          required_fields.reject { |field| !send(field).nil? && !send(field).to_s.empty? }
+        end
+      end
+    end
+  end
+end

data/lib/rma/payment/gateway/debit_request.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "uri"
+require "securerandom"
+
+module Rma
+  module Payment
+    module Gateway
+      # Authorization class for RMA Payment Gateway.
+      # Handles authentication and authorization for the RMA Payment Gateway client.
+      #
+      # @example
+      #   auth = Rma::Payment::Gateway::Authorization.new(client)
+      #   auth.call(order_no, amount, email)
+      #
+      # @param client [Rma::Payment::Gateway::Client] Client instance
+      class DebitRequest
+        attr_reader :client, :transaction_id, :otp
+
+        def initialize(client)
+          @client = client
+        end
+
+        # Fetch debit request
+        # Returns the debit request string
+        def call(transaction_id, otp)
+          @transaction_id = transaction_id
+          @otp = otp
+          response = client.post(body: debit_request_body)
+
+          validate_debit_request_response!(response)
+
+          response["result"]
+        rescue StandardError => e
+          raise AuthenticationError, "Failed to fetch debit request: #{e.message}"
+        end
+
+        private
+
+        def debit_request_body
+          params = {
+            bfs_bfsTxnId: transaction_id,
+            bfs_remitterOtp: otp,
+            bfs_benfId: client.config.beneficiary_id,
+            bfs_msgType: "DR"
+          }
+
+          # Convert to URL-encoded format
+          URI.encode_www_form(params)
+        end
+
+        def validate_debit_request_response!(response)
+          unless response.is_a?(Hash) && response["result"]["bfs_responseCode"] == "00"
+            error_detail = response["result"]["bfs_responseDesc"] || "Unknown error"
+            raise AuthenticationError, "Debit request failed: #{error_detail}"
+          end
+
+          return if response["result"]
+
+          raise AuthenticationError, "No response data in response"
+        end
+      end
+    end
+  end
+end

data/lib/rma/payment/gateway/errors.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Rma
+  module Payment
+    module Gateway
+      class Error < StandardError; end
+
+      class ConfigurationError < Error; end
+
+      class AuthenticationError < Error; end
+
+      class InvalidParameterError < Error
+        attr_reader :response_code, :response_detail
+
+        def initialize(message, response_code: 422, response_detail: "Invalid parameters")
+          super(message)
+          @response_code = response_code
+          @response_detail = response_detail
+        end
+      end
+
+      class APIError < Error
+        attr_reader :response_code, :response_message, :response_description, :response_detail
+
+        def initialize(message, response_code: 422, response_message: "Invalid parameters",
+                       response_description: "Invalid parameters", response_detail: "Invalid parameters")
+          super(message)
+          @response_code = response_code
+          @response_message = response_message
+          @response_description = response_description
+          @response_detail = response_detail
+        end
+      end
+
+      class NetworkError < Error; end
+
+      class SignatureError < Error; end
+
+      class TransactionError < APIError; end
+    end
+  end
+end

data/lib/rma/payment/gateway/utils.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Rma
+  module Payment
+    module Gateway
+      module Utils
+        # Generate ISO 8601 timestamp
+        # @param time [Time] Optional time object (defaults to current time)
+        # @return [String] ISO 8601 formatted timestamp
+        def self.generate_timestamp(time = Time.now)
+          time.utc.strftime("%Y%m%d%H%M%S")
+        end
+
+        # Validate account number format
+        # @param account_number [String] Account number to validate
+        # @return [Boolean] True if valid format
+        def self.valid_account_number?(account_number)
+          return false if account_number.nil? || account_number.empty?
+
+          # Account numbers should be numeric and between 8-15 digits
+          account_number.to_s.match?(/^\d{8,15}$/)
+        end
+
+        # Validate phone number format (Bhutan)
+        # @param phone_number [String] Phone number to validate
+        # @return [Boolean] True if valid format
+        def self.valid_phone_number?(phone_number)
+          return false if phone_number.nil? || phone_number.empty?
+
+          # Bhutan phone numbers are typically 8 digits
+          phone_number.to_s.match?(/^\d{8}$/)
+        end
+
+        # Validate email format
+        # @param email [String] Email to validate
+        # @return [Boolean] True if valid format
+        def self.valid_email?(email)
+          return false if email.nil? || email.empty?
+
+          email.to_s.match?(/\A[\w+\-.]+@[a-z\d-]+(\.[a-z\d-]+)*\.[a-z]+\z/i)
+        end
+
+        # Validate amount
+        # @param amount [Numeric] Amount to validate
+        # @return [Boolean] True if valid
+        def self.valid_amount?(amount)
+          return false if amount.nil?
+
+          amount.is_a?(Numeric) && amount >= 0
+        end
+
+        # Format amount to 2 decimal places
+        # @param amount [Numeric] Amount to format
+        # @return [String] Formatted amount
+        def self.format_amount(amount)
+          format("%.2f", amount.to_f)
+        end
+
+        # Validate date format (YYYY-MM-DD)
+        # @param date_string [String] Date string to validate
+        # @return [Boolean] True if valid format
+        def self.valid_date_format?(date_string)
+          return false if date_string.nil? || date_string.empty?
+
+          date_string.to_s.match?(/^\d{4}-\d{2}-\d{2}$/)
+        end
+
+        # Parse date string
+        # @param date_string [String] Date string in YYYY-MM-DD format
+        # @return [Date, nil] Parsed date or nil if invalid
+        def self.parse_date(date_string)
+          return nil unless valid_date_format?(date_string)
+
+          Date.parse(date_string)
+        rescue ArgumentError
+          nil
+        end
+
+        # Sanitize string for API request
+        # @param str [String] String to sanitize
+        # @return [String] Sanitized string
+        def self.sanitize_string(str)
+          return "" if str.nil?
+
+          str.to_s.strip
+        end
+
+        # Mask sensitive data for logging
+        # @param data [String] Sensitive data to mask
+        # @param visible_chars [Integer] Number of characters to show at start and end
+        # @return [String] Masked string
+        def self.mask_sensitive(data, visible_chars = 4)
+          return "" if data.nil? || data.empty?
+
+          data_str = data.to_s
+          return data_str if data_str.length <= visible_chars * 2
+
+          "#{data_str[0...visible_chars]}#{"*" * (data_str.length - visible_chars * 2)}#{data_str[-visible_chars..]}"
+        end
+
+        # Bank codes mapping
+        BANK_CODES = {
+          "1010" => "Bank of Bhutan (BOBL)",
+          "1020" => "Bhutan National Bank (BNBL)",
+          "1030" => "Druk PNB Bank Limited (DPNBL)",
+          "1040" => "Tashi Bank (TBank)",
+          "1050" => "Bhutan Development Bank Limited (BDBL)",
+          "1060" => "Digital Kidu (DK Bank)"
+        }.freeze
+
+        # Get bank name from code
+        # @param bank_code [String] Bank code
+        # @return [String, nil] Bank name or nil if not found
+        def self.bank_name(bank_code)
+          BANK_CODES[bank_code.to_s]
+        end
+
+        # Validate bank code
+        # @param bank_code [String] Bank code to validate
+        # @return [Boolean] True if valid
+        def self.valid_bank_code?(bank_code)
+          BANK_CODES.key?(bank_code.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/rma/payment/gateway/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Rma
+  module Payment
+    module Gateway
+      VERSION = "1.0.0"
+    end
+  end
+end

data/lib/rma/payment/gateway.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "gateway/version"
+
+module Rma
+  module Payment
+    module Gateway
+      class Error < StandardError; end
+
+      class << self
+        attr_accessor :configuration
+      end
+
+      def self.configure
+        self.configuration ||= Configuration.new
+        yield(configuration)
+      end
+
+      def self.client
+        Client.new(configuration)
+      end
+    end
+  end
+end

data/sig/rma/payment/gateway.rbs

@@ -0,0 +1,8 @@
+module Rma
+  module Payment
+    module Gateway
+      VERSION: String
+      # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+    end
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: rma-payment-gateway
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Tashi Dendup
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby gem for integrating with RMA Payment Gateway API, including Payment
+  Authorization, Debit payment request, and Payment OTP confirmation.
+email:
+- tashii.dendupp@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- README.md
+- Rakefile
+- docs/API.md
+- docs/EXAMPLES.md
+- docs/FLOW_DIAGRAM.md
+- docs/QUICK_REFERENCE.md
+- docs/README.md
+- docs/SECURITY.md
+- docs/USAGE_GUIDE.md
+- lib/rma/payment/gateway.rb
+- lib/rma/payment/gateway/account_inquiry.rb
+- lib/rma/payment/gateway/authorization.rb
+- lib/rma/payment/gateway/client.rb
+- lib/rma/payment/gateway/configuration.rb
+- lib/rma/payment/gateway/debit_request.rb
+- lib/rma/payment/gateway/errors.rb
+- lib/rma/payment/gateway/utils.rb
+- lib/rma/payment/gateway/version.rb
+- sig/rma/payment/gateway.rbs
+homepage: https://github.com/dcplbt/rma-payment-gateway
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/dcplbt/rma-payment-gateway
+  source_code_uri: https://github.com/dcplbt/rma-payment-gateway
+  changelog_uri: https://github.com/dcplbt/rma-payment-gateway/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: RMA Payment Gateway
+test_files: []