dk_payment_gateway 1.0.0

data/lib/dk_payment_gateway/client.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module DkPaymentGateway
+  class Client
+    attr_reader :config, :access_token, :private_key
+
+    def initialize(config = nil)
+      @config = config || DkPaymentGateway.configuration
+      validate_configuration!
+      @access_token = nil
+      @private_key = nil
+    end
+
+    # Authentication methods
+    def authenticate!
+      auth = Authentication.new(self)
+      @access_token = auth.fetch_token
+      @private_key = auth.fetch_private_key
+      self
+    end
+
+    # Pull Payment methods
+    def pull_payment
+      @pull_payment ||= PullPayment.new(self)
+    end
+
+    # Intra Transaction methods
+    def intra_transaction
+      @intra_transaction ||= IntraTransaction.new(self)
+    end
+
+    # QR Payment methods
+    def qr_payment
+      @qr_payment ||= QrPayment.new(self)
+    end
+
+    # Transaction Status methods
+    def transaction_status
+      @transaction_status ||= TransactionStatus.new(self)
+    end
+
+    # HTTP request methods
+    def post(path, body: {}, headers: {}, skip_auth: false)
+      request(:post, path, body: body, headers: headers, skip_auth: skip_auth)
+    end
+
+    def get(path, params: {}, headers: {}, skip_auth: false)
+      request(:get, path, params: params, headers: headers, skip_auth: skip_auth)
+    end
+
+    private
+
+    def validate_configuration!
+      raise ConfigurationError, "Configuration is required" if config.nil?
+      unless config.valid?
+        raise ConfigurationError, "Missing required configuration fields: #{config.missing_fields.join(', ')}"
+      end
+    end
+
+    def request(method, path, body: {}, params: {}, headers: {}, skip_auth: false)
+      url = "#{config.base_url}#{path}"
+      
+      response = connection.send(method) do |req|
+        req.url path
+        req.headers = build_headers(headers, skip_auth)
+        req.body = body.to_json if method == :post && !body.empty?
+        req.params = params if method == :get && !params.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 :json
+        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 = {}, skip_auth = false)
+      headers = {
+        "Content-Type" => "application/json",
+        "X-gravitee-api-key" => config.api_key
+      }
+
+      unless skip_auth
+        headers["Authorization"] = "Bearer #{access_token}" if access_token
+        headers["source_app"] = config.source_app
+      end
+
+      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["response_message"] || body["response_detail"] || "Client error"
+      
+      raise InvalidParameterError.new(
+        error_message,
+        response_code: body["response_code"],
+        response_detail: body["response_detail"]
+      )
+    end
+
+    def handle_server_error(response)
+      body = response.body || {}
+      error_message = body["response_description"] || body["response_message"] || "Server error"
+      
+      raise APIError.new(
+        error_message,
+        response_code: body["response_code"],
+        response_message: body["response_message"],
+        response_description: body["response_description"]
+      )
+    end
+  end
+end
+

data/lib/dk_payment_gateway/configuration.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module DkPaymentGateway
+  class Configuration
+    attr_accessor :base_url, :api_key, :username, :password, :client_id,
+                  :client_secret, :source_app, :timeout, :open_timeout
+
+    def initialize
+      @base_url = ENV['DK_BASE_URL']
+      @api_key = ENV['DK_API_KEY']
+      @username = ENV['DK_USERNAME']
+      @password = ENV['DK_PASSWORD']
+      @client_id = ENV['DK_CLIENT_ID']
+      @client_secret = ENV['DK_CLIENT_SECRET']
+      @source_app = ENV['DK_SOURCE_APP']
+      @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 api_key username password client_id client_secret source_app]
+    end
+
+    def missing_fields
+      required_fields.reject { |field| !send(field).nil? && !send(field).to_s.empty? }
+    end
+  end
+end

data/lib/dk_payment_gateway/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module DkPaymentGateway
+  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: nil, response_detail: nil)
+      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: nil, response_message: nil, 
+                   response_description: nil, response_detail: nil)
+      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
+

data/lib/dk_payment_gateway/intra_transaction.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module DkPaymentGateway
+  class IntraTransaction
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Intra (DK - DK) Beneficiary Account Inquiry
+    # Validates beneficiary account details before initiating a fund transfer
+    #
+    # @param params [Hash] Account inquiry parameters
+    # @option params [String] :request_id Unique identifier for the inquiry request
+    # @option params [Numeric] :amount Transaction amount
+    # @option params [String] :currency Currency code (e.g., "BTN")
+    # @option params [String] :bene_bank_code Beneficiary bank code (1060 for intra)
+    # @option params [String] :bene_account_number Beneficiary account number
+    # @option params [String] :source_account_name Source account holder name (optional)
+    # @option params [String] :source_account_number Source account number
+    #
+    # @return [Hash] Response containing inquiry_id and account_name
+    def account_inquiry(params)
+      validate_inquiry_params!(params)
+      
+      request_body = build_inquiry_body(params)
+      signature_headers = generate_signature_headers(request_body)
+
+      response = client.post(
+        "/v1/beneficiary/account_inquiry",
+        body: request_body,
+        headers: signature_headers
+      )
+
+      validate_response!(response, "Account Inquiry")
+      response["response_data"]
+    end
+
+    # Intra (DK - DK) Fund Transfer
+    # Initiates a fund transfer after successful account inquiry
+    #
+    # @param params [Hash] Fund transfer parameters
+    # @option params [String] :request_id Unique identifier for the request
+    # @option params [String] :inquiry_id Inquiry ID from account_inquiry
+    # @option params [String] :source_app Source application identifier
+    # @option params [Numeric] :transaction_amount Amount to transfer
+    # @option params [String] :currency Currency code (e.g., "BTN")
+    # @option params [String] :transaction_datetime Transaction timestamp (ISO 8601)
+    # @option params [String] :bene_bank_code Beneficiary bank code
+    # @option params [String] :bene_account_number Beneficiary account number
+    # @option params [String] :bene_cust_name Beneficiary customer name
+    # @option params [String] :source_account_name Source account holder name (optional)
+    # @option params [String] :source_account_number Source account number
+    # @option params [String] :payment_type Payment type (should be "INTRA" for DK-DK)
+    # @option params [String] :narration Transaction description/purpose
+    #
+    # @return [Hash] Response containing inquiry_id and txn_status_id
+    def fund_transfer(params)
+      validate_transfer_params!(params)
+      
+      request_body = build_transfer_body(params)
+      signature_headers = generate_signature_headers(request_body)
+
+      response = client.post(
+        "/v1/initiate/transaction",
+        body: request_body,
+        headers: signature_headers
+      )
+
+      validate_response!(response, "Fund Transfer")
+      response["response_data"]
+    end
+
+    private
+
+    def build_inquiry_body(params)
+      {
+        request_id: params[:request_id],
+        amount: params[:amount].to_s,
+        currency: params[:currency],
+        bene_bank_code: params[:bene_bank_code],
+        bene_account_number: params[:bene_account_number],
+        soure_account_number: params[:source_account_number] # Note: API has typo "soure"
+      }.tap do |body|
+        body[:source_account_name] = params[:source_account_name] if params[:source_account_name]
+      end
+    end
+
+    def build_transfer_body(params)
+      {
+        request_id: params[:request_id],
+        inquiry_id: params[:inquiry_id],
+        transaction_datetime: params[:transaction_datetime],
+        source_app: params[:source_app] || client.config.source_app,
+        transaction_amount: params[:transaction_amount],
+        currency: params[:currency],
+        payment_type: params[:payment_type] || "INTRA",
+        source_account_number: params[:source_account_number],
+        bene_cust_name: params[:bene_cust_name],
+        bene_account_number: params[:bene_account_number],
+        bene_bank_code: params[:bene_bank_code],
+        narration: params[:narration]
+      }.tap do |body|
+        body[:source_account_name] = params[:source_account_name] if params[:source_account_name]
+      end
+    end
+
+    def validate_inquiry_params!(params)
+      required = [:request_id, :amount, :currency, :bene_bank_code, 
+                  :bene_account_number, :source_account_number]
+      
+      missing = required.select { |key| params[key].nil? || params[key].to_s.empty? }
+      
+      raise InvalidParameterError, "Missing required parameters: #{missing.join(', ')}" unless missing.empty?
+    end
+
+    def validate_transfer_params!(params)
+      required = [:request_id, :inquiry_id, :transaction_amount, :currency,
+                  :transaction_datetime, :bene_bank_code, :bene_account_number,
+                  :bene_cust_name, :source_account_number, :narration]
+      
+      missing = required.select { |key| params[key].nil? || params[key].to_s.empty? }
+      
+      raise InvalidParameterError, "Missing required parameters: #{missing.join(', ')}" unless missing.empty?
+    end
+
+    def validate_response!(response, operation)
+      unless response.is_a?(Hash) && response["response_code"] == "0000"
+        error_msg = response["response_description"] || response["response_message"] || "Unknown error"
+        raise TransactionError.new(
+          "#{operation} failed: #{error_msg}",
+          response_code: response["response_code"],
+          response_message: response["response_message"],
+          response_description: response["response_description"]
+        )
+      end
+    end
+
+    def generate_signature_headers(request_body)
+      raise SignatureError, "Private key not available. Call client.authenticate! first" unless client.private_key
+      
+      Signature.generate(client.private_key, request_body)
+    end
+  end
+end
+

data/lib/dk_payment_gateway/pull_payment.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module DkPaymentGateway
+  class PullPayment
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Payment Gateway Authorization (Account inquiry and OTP request)
+    # 
+    # @param params [Hash] Authorization parameters
+    # @option params [String] :transaction_datetime Transaction timestamp in UTC (ISO 8601)
+    # @option params [String] :stan_number 12-digit unique transaction number
+    # @option params [Numeric] :transaction_amount Amount of the transaction
+    # @option params [Numeric] :transaction_fee Transaction fee (use 0 if no fee)
+    # @option params [String] :payment_desc Payment description
+    # @option params [String] :account_number Beneficiary account number
+    # @option params [String] :account_name Beneficiary account name
+    # @option params [String] :email_id Beneficiary email (optional)
+    # @option params [String] :phone_number Beneficiary phone number
+    # @option params [String] :remitter_account_number Remitter account number
+    # @option params [String] :remitter_account_name Remitter account name
+    # @option params [String] :remitter_bank_id Remitter bank identifier
+    #
+    # @return [Hash] Response containing bfs_txn_id, stan_number, account_number, remitter_account_number
+    def authorize(params)
+      validate_authorization_params!(params)
+      
+      request_body = build_authorization_body(params)
+      signature_headers = generate_signature_headers(request_body)
+
+      response = client.post(
+        "/v1/account_auth/pull-payment",
+        body: request_body,
+        headers: signature_headers
+      )
+
+      validate_response!(response, "Authorization")
+      response["response_data"]
+    end
+
+    # Payment Gateway Debit Request
+    # Completes a previously authorized payment by verifying OTP
+    #
+    # @param params [Hash] Debit request parameters
+    # @option params [String] :request_id Unique identifier for the request
+    # @option params [String] :bfs_txn_id Transaction ID from authorization
+    # @option params [String] :bfs_remitter_otp OTP sent to remitter
+    # @option params [String] :bfs_order_no Order number (optional)
+    #
+    # @return [Hash] Response containing bfs_txn_id, code, description
+    def debit(params)
+      validate_debit_params!(params)
+      
+      request_body = build_debit_body(params)
+      signature_headers = generate_signature_headers(request_body)
+
+      response = client.post(
+        "/v1/debit_request/pull-payment",
+        body: request_body,
+        headers: signature_headers
+      )
+
+      validate_response!(response, "Debit")
+      response["response_data"]
+    end
+
+    # Generate STAN number
+    # @param source_app_suffix [String] Last 4 digits of source_app (e.g., "0201")
+    # @param transaction_identifier [String] 8-digit identifier (timestamp or counter)
+    # @return [String] 12-digit STAN number
+    def self.generate_stan(source_app_suffix, transaction_identifier = nil)
+      suffix = source_app_suffix.to_s[-4..]
+      
+      identifier = if transaction_identifier
+        transaction_identifier.to_s[-8..]
+      else
+        # Generate from current timestamp (HHMMSSMS format)
+        time = Time.now
+        format("%02d%02d%02d%02d", time.hour, time.min, time.sec, time.usec / 10000)
+      end
+
+      "#{suffix}#{identifier}"
+    end
+
+    private
+
+    def build_authorization_body(params)
+      {
+        transaction_datetime: params[:transaction_datetime],
+        stan_number: params[:stan_number],
+        transaction_amount: params[:transaction_amount],
+        transaction_fee: params[:transaction_fee] || 0,
+        payment_desc: params[:payment_desc],
+        account_number: params[:account_number],
+        account_name: params[:account_name],
+        phone_number: params[:phone_number],
+        remitter_account_number: params[:remitter_account_number],
+        remitter_account_name: params[:remitter_account_name],
+        remitter_bank_id: params[:remitter_bank_id]
+      }.tap do |body|
+        body[:email_id] = params[:email_id] if params[:email_id]
+      end
+    end
+
+    def build_debit_body(params)
+      {
+        request_id: params[:request_id],
+        bfs_bfsTxnId: params[:bfs_txn_id],
+        bfs_remitter_Otp: params[:bfs_remitter_otp]
+      }.tap do |body|
+        body[:bfs_orderNo] = params[:bfs_order_no] if params[:bfs_order_no]
+      end
+    end
+
+    def validate_authorization_params!(params)
+      required = [:transaction_datetime, :stan_number, :transaction_amount, :payment_desc,
+                  :account_number, :account_name, :phone_number, :remitter_account_number,
+                  :remitter_account_name, :remitter_bank_id]
+      
+      missing = required.select { |key| params[key].nil? || params[key].to_s.empty? }
+      
+      raise InvalidParameterError, "Missing required parameters: #{missing.join(', ')}" unless missing.empty?
+    end
+
+    def validate_debit_params!(params)
+      required = [:request_id, :bfs_txn_id, :bfs_remitter_otp]
+      
+      missing = required.select { |key| params[key].nil? || params[key].to_s.empty? }
+      
+      raise InvalidParameterError, "Missing required parameters: #{missing.join(', ')}" unless missing.empty?
+    end
+
+    def validate_response!(response, operation)
+      unless response.is_a?(Hash) && response["response_code"] == "0000"
+        error_msg = response["response_description"] || response["response_message"] || "Unknown error"
+        raise TransactionError.new(
+          "#{operation} failed: #{error_msg}",
+          response_code: response["response_code"],
+          response_message: response["response_message"],
+          response_description: response["response_description"]
+        )
+      end
+    end
+
+    def generate_signature_headers(request_body)
+      raise SignatureError, "Private key not available. Call client.authenticate! first" unless client.private_key
+      
+      Signature.generate(client.private_key, request_body)
+    end
+  end
+end
+

data/lib/dk_payment_gateway/qr_payment.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module DkPaymentGateway
+  class QrPayment
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Generate QR Code for payment transaction
+    # 
+    # If amount = 0, generates a Static QR (payer enters amount)
+    # If amount > 0, generates a Dynamic QR (amount is fixed)
+    #
+    # @param params [Hash] QR generation parameters
+    # @option params [String] :request_id Unique identifier for the request
+    # @option params [String] :currency Currency code (e.g., "BTN")
+    # @option params [String] :bene_account_number Beneficiary account number
+    # @option params [Numeric] :amount Transaction amount (0 for static QR, >0 for dynamic QR)
+    # @option params [String] :mcc_code Merchant Category Code (ISO 18245)
+    # @option params [String] :remarks Optional notes or comments (optional)
+    #
+    # @return [Hash] Response containing base64 encoded QR image
+    def generate_qr(params)
+      validate_qr_params!(params)
+      
+      request_body = build_qr_body(params)
+      signature_headers = generate_signature_headers(request_body)
+
+      response = client.post(
+        "/v1/generate_qr",
+        body: request_body,
+        headers: signature_headers
+      )
+
+      validate_response!(response, "QR Generation")
+      response["response_data"]
+    end
+
+    # Decode base64 QR image and save to file
+    # @param base64_image [String] Base64 encoded image
+    # @param file_path [String] Path to save the image
+    def save_qr_image(base64_image, file_path)
+      require "base64"
+      
+      image_data = Base64.decode64(base64_image)
+      File.open(file_path, "wb") { |f| f.write(image_data) }
+      
+      file_path
+    end
+
+    private
+
+    def build_qr_body(params)
+      {
+        request_id: params[:request_id],
+        currency: params[:currency],
+        bene_account_number: params[:bene_account_number],
+        amount: params[:amount],
+        mcc_code: params[:mcc_code]
+      }.tap do |body|
+        body[:remarks] = params[:remarks] if params[:remarks]
+      end
+    end
+
+    def validate_qr_params!(params)
+      required = [:request_id, :currency, :bene_account_number, :amount, :mcc_code]
+      
+      missing = required.select { |key| params[key].nil? }
+      
+      raise InvalidParameterError, "Missing required parameters: #{missing.join(', ')}" unless missing.empty?
+
+      # Validate amount is numeric
+      unless params[:amount].is_a?(Numeric) || params[:amount].to_s.match?(/^\d+(\.\d+)?$/)
+        raise InvalidParameterError, "Amount must be a valid number"
+      end
+    end
+
+    def validate_response!(response, operation)
+      unless response.is_a?(Hash) && response["response_code"] == "0000"
+        error_msg = response["response_detail"] || response["response_message"] || "Unknown error"
+        raise TransactionError.new(
+          "#{operation} failed: #{error_msg}",
+          response_code: response["response_code"],
+          response_detail: response["response_detail"]
+        )
+      end
+    end
+
+    def generate_signature_headers(request_body)
+      raise SignatureError, "Private key not available. Call client.authenticate! first" unless client.private_key
+      
+      Signature.generate(client.private_key, request_body)
+    end
+  end
+end
+

data/lib/dk_payment_gateway/signature.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "jwt"
+require "base64"
+require "json"
+require "time"
+require "securerandom"
+
+module DkPaymentGateway
+  class Signature
+    attr_reader :private_key
+
+    def initialize(private_key)
+      @private_key = private_key
+    end
+
+    # Generate signature headers for a request
+    # Returns a hash with DK-Signature, DK-Timestamp, and DK-Nonce
+    def generate_headers(request_body)
+      timestamp = generate_timestamp
+      nonce = generate_nonce
+      signature = sign_request(request_body, timestamp, nonce)
+
+      {
+        "DK-Signature" => "DKSignature #{signature}",
+        "DK-Timestamp" => timestamp,
+        "DK-Nonce" => nonce
+      }
+    end
+
+    private
+
+    # Generate ISO 8601 timestamp
+    def generate_timestamp
+      Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+    end
+
+    # Generate unique alphanumeric nonce
+    def generate_nonce
+      SecureRandom.hex(16)
+    end
+
+    # Sign the request using RS256 algorithm
+    def sign_request(request_body, timestamp, nonce)
+      # Serialize request body to canonical JSON (sorted keys, no spaces)
+      request_body_str = JSON.generate(request_body, space: "", object_nl: "", array_nl: "")
+      
+      # Base64 encode the request body
+      body_base64 = Base64.strict_encode64(request_body_str)
+
+      # Create the payload for signing
+      token_payload = {
+        "data" => body_base64,
+        "timestamp" => timestamp,
+        "nonce" => nonce
+      }
+
+      # Sign using RS256
+      JWT.encode(token_payload, OpenSSL::PKey::RSA.new(private_key), "RS256")
+    rescue => e
+      raise SignatureError, "Failed to generate signature: #{e.message}"
+    end
+
+    class << self
+      # Convenience method to generate signature headers
+      def generate(private_key, request_body)
+        new(private_key).generate_headers(request_body)
+      end
+    end
+  end
+end
+