paygate_pk 0.2.3 → 1.0.0

data/lib/paygate_pk/providers/pay_fast/auth.rb

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-require "date"
-
-module PaygatePk
-  module Providers
-    module PayFast
-      # Auth client for PayFast API
-      class Auth < Client
-        ENDPOINT = "/Ecommerce/api/Transaction/GetAccessToken"
-
-        # Returns Contracts::AccessToken
-        # Required by PayFast: MERCHANT_ID, SECURED_KEY, BASKET_ID, TXNAMT, CURRENCY_CODE
-        #
-        def get_access_token(basket_id:, amount:, currency: PaygatePk.config.default_currency, endpoint: ENDPOINT)
-          ensure_config!
-          ensure_args!(basket_id: basket_id, amount: amount, currency: currency)
-
-          # Guide endpoint: .../Ecommerce/api/Transaction/GetAccessToken
-          resp  = http.post(endpoint,
-                            form: payload(basket_id, amount, currency))
-          token = resp.is_a?(Hash) ? (resp["ACCESS_TOKEN"] || resp["access_token"]) : nil
-          raise AuthError, "missing ACCESS_TOKEN in response" unless token
-
-          Contracts::AccessToken.new(token: token, raw: resp)
-        end
-
-        private
-
-        def base_url
-          config.base_url
-        end
-
-        def ensure_config!
-          missing = []
-          missing << :merchant_id if @config.merchant_id.to_s.strip.empty?
-          missing << :secured_key if @config.secured_key.to_s.strip.empty?
-          raise ConfigurationError, "PayFast config missing: #{missing.join(", ")}" unless missing.empty?
-        end
-
-        def ensure_args!(basket_id:, amount:, currency:)
-          missing = []
-          missing << :basket_id if basket_id.to_s.strip.empty?
-          missing << :amount if amount.nil?
-          missing << :currency if currency.to_s.strip.empty?
-          raise ValidationError, "missing required args: #{missing.join(", ")}" unless missing.empty?
-        end
-
-        def payload(basket_id, amount, currency)
-          {
-            "MERCHANT_ID" => @config.merchant_id,
-            "SECURED_KEY" => @config.secured_key,
-            "BASKET_ID" => basket_id,
-            "TXNAMT" => amount.to_s,
-            "CURRENCY_CODE" => currency
-          }
-        end
-      end
-    end
-  end
-end

data/lib/paygate_pk/providers/pay_fast/checkout.rb

@@ -1,157 +0,0 @@
-# lib/paygate_pk/providers/pay_fast/checkout.rb
-# frozen_string_literal: true
-
-require "securerandom"
-require "date"
-require "nokogiri"
-
-module PaygatePk
-  module Providers
-    module PayFast
-      # Builds and submits a hosted checkout request to PayFast.
-      #
-      # Usage:
-      #   client   = PaygatePk::Providers::PayFast::Checkout.new(config: PaygatePk.config.payfast)
-      #   checkout = client.create!(
-      #     token: token.token,
-      #     basket_id: "B-1001",
-      #     amount: 1500,
-      #     customer: { mobile: "03xxxxxxxxx", email: "buyer@example.com" },
-      #     success_url: "...",
-      #     failure_url: "...",
-      #     description: "Order #1001",
-      #     checkout_mode: :immediate
-      #   )
-      class Checkout < Client
-        ENDPOINT = "/Ecommerce/api/Transaction/PostTransaction"
-
-        REQUIRED_ROOT_KEYS     = %i[token basket_id amount success_url failure_url description].freeze
-        REQUIRED_CUSTOMER_KEYS = %i[mobile email].freeze
-
-        # Creates a hosted checkout via PayFast.
-        #
-        # @param token [String] ACCESS_TOKEN from GetAccessToken
-        # @param basket_id [String]
-        # @param amount [Integer, Float] rupees
-        # @param customer [Hash] keys: :mobile, :email
-        # @param success_url [String]
-        # @param failure_url [String]
-        # @param description [String] TXNDESC
-        # @param order_date [Date] defaults: Date.today
-        # @param checkout_mode [Symbol] :immediate or :delayed (defaults from config)
-        # @param endpoint [Symbol] default to ENDPOINT constant
-
-        # @return [PaygatePk::Contracts::HostedCheckout]
-        def create!(opts: {})
-          validate_config!
-          validate_args!(opts)
-
-          form = build_form(opts)
-
-          response = http.post(opts[:endpoint] || ENDPOINT, form: form)
-
-          PaygatePk::Contracts::HostedCheckout.new(
-            provider: :payfast,
-            basket_id: opts[:basket_id],
-            amount: opts[:amount],
-            url: PaygatePk::Util::Html.first_anchor_href(response),
-            form: PaygatePk::Util::Html.extract_form(response),
-            raw: response
-          )
-        end
-
-        private
-
-        def base_url
-          config.base_url
-        end
-
-        # -- Validation ---------------------------------------------------------
-
-        def validate_config!
-          missing = []
-          missing << :merchant_id if blank?(config.merchant_id)
-          missing << :secured_key if blank?(config.secured_key)
-          raise PaygatePk::ConfigurationError, "PayFast config missing: #{missing.join(", ")}" unless missing.empty?
-        end
-
-        def validate_args!(opts)
-          missing = []
-          REQUIRED_ROOT_KEYS.each do |k|
-            v = opts[k]
-            missing << k if k == :amount ? opts[:amount].nil? : blank?(v)
-          end
-          REQUIRED_CUSTOMER_KEYS.each { |k| missing << :"customer.#{k}" if blank?(opts[:customer][k]) }
-          raise PaygatePk::ValidationError, "missing required args: #{missing.join(", ")}" unless missing.empty?
-        end
-
-        # -- Builders -----------------------------------------------------------
-
-        def merchant_params
-          {
-            "MERCHANT_ID" => config.merchant_id,
-            "MERCHANT_NAME" => merchant_name_default
-          }
-        end
-
-        def order_params(opts)
-          {
-            "BASKET_ID" => opts[:basket_id],
-            "TXNDESC" => opts[:description],
-            "TXNAMT" => opts[:amount].to_s,
-            "CURRENCY_CODE" => PaygatePk.config.default_currency,
-            "ORDER_DATE" => (opts[:order_date] || Date.today).to_s,
-            "SUCCESS_URL" => opts[:success_url],
-            "FAILURE_URL" => opts[:failure_url],
-            "CHECKOUT_URL" => normalize_checkout_mode(opts[:checkout_mode] || config.checkout_mode)
-          }
-        end
-
-        def customer_params(opts)
-          {
-            "CUSTOMER_MOBILE_NO" => opts[:customer][:mobile],
-            "CUSTOMER_EMAIL_ADDRESS" => opts[:customer][:email]
-          }
-        end
-
-        def generic_params(opts)
-          {
-            "TOKEN" => opts[:token],
-            "PROCCODE" => "00",
-            "SIGNATURE" => SecureRandom.hex(16),
-            "VERSION" => PaygatePk::VERSION
-          }
-        end
-
-        def build_form(opts)
-          merchant_params
-            .merge(order_params(opts))
-            .merge(customer_params(opts))
-            .merge(generic_params(opts))
-        end
-
-        # -- Helpers ------------------------------------------------------------
-
-        def normalize_checkout_mode(mode)
-          case mode&.to_sym
-          when :delayed then "DELAYED"
-          when :immediate, nil then "IMMEDIATE"
-          else
-            # Be lenient but explicit: unknown symbols fall back to IMMEDIATE
-            "IMMEDIATE"
-          end
-        end
-
-        def merchant_name_default
-          # Kept blank as many integrations treat it as optional; override here
-          # later if you decide to expose it via config.
-          ""
-        end
-
-        def blank?(value)
-          value.nil? || (value.respond_to?(:empty?) && value.empty?)
-        end
-      end
-    end
-  end
-end

data/lib/paygate_pk/providers/pay_fast/client.rb

@@ -1,53 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../http/client"
-require_relative "../../version"
-
-module PaygatePk
-  module Providers
-    module PayFast
-      # HTTP client for PayFast API
-      class Client
-        def initialize(config: PaygatePk.config.pay_fast)
-          @config = config
-        end
-
-        def get_access_token(**params)
-          Auth.new(config: @config).get_access_token(**params)
-        end
-
-        def verify_ipn!(params)
-          Webhook.new.verify!(params)
-        end
-
-        def create_checkout(**params)
-          Checkout.new(config: @config).create!(**params)
-        end
-
-        def get_bearer_token(**params)
-          Tokenization::Token.new(config: @config).get(**params)
-        end
-
-        def instruments(**params)
-          Tokenization::Instrument.new(config: @config).list(**params)
-        end
-
-        private
-
-        attr_reader :config
-
-        def http
-          raise ConfigurationError, "PayFast base_url not set" unless config.base_url
-
-          PaygatePk::HTTP::Client.new(
-            base_url: base_url,
-            headers: { "Accept" => "application/json" },
-            timeouts: PaygatePk.config.timeouts,
-            retry_conf: PaygatePk.config.retry,
-            logger: PaygatePk.config.logger
-          )
-        end
-      end
-    end
-  end
-end

data/lib/paygate_pk/providers/pay_fast/tokenization/instrument.rb

@@ -1,63 +0,0 @@
-# frozen_string_literal: true
-
-module PaygatePk
-  module Providers
-    module PayFast
-      module Tokenization
-        # used to generate the bearer_token
-        class Instrument < PaygatePk::Providers::PayFast::Client
-          INSTRUMENTS_ENDPOINT = "/api/user/instruments"
-
-          def list(token:, user_id:, mobile_number:, options: {})
-            ensure_present!(token: token,
-                            user_id: user_id,
-                            mobile_number: mobile_number)
-
-            resp = http.get(INSTRUMENTS_ENDPOINT,
-                            params: body(user_id, mobile_number, options),
-                            headers: { "Authorization" => "Bearer #{token}" })
-
-            # Response is an array of hashes with instrument_token, account_type, description, instrument_alias
-            Array(resp).map do |h|
-              PaygatePk::Contracts::Instrument.new(
-                instrument_token: h["instrument_token"],
-                account_type: h["account_type"],
-                description: h["description"],
-                instrument_alias: h["instrument_alias"],
-                raw: h
-              )
-            end
-          end
-
-          private
-
-          def base_url
-            config.api_base_url
-          end
-
-          def body(user_id, mobile_no, options)
-            attrs = {
-              "merchant_user_id" => user_id,
-              "user_mobile_number" => mobile_no
-            }
-
-            # rubocop:disable Naming/VariableNumber
-            attrs["customer_ip"] = options[:customer_ip] if options[:customer_ip]
-            attrs["reserved_1"]  = options[:reserved_1] if options[:reserved_1]
-            attrs["reserved_2"]  = options[:reserved_2] if options[:reserved_2]
-            attrs["reserved_3"]  = options[:reserved_3] if options[:reserved_3]
-            attrs["api_version"] = options[:api_version] if options[:api_version]
-            # rubocop:enable Naming/VariableNumber
-
-            attrs
-          end
-
-          def ensure_present!(**pairs)
-            missing = pairs.select { |_k, v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }.keys
-            raise PaygatePk::ValidationError, "missing required args: #{missing.join(", ")}" unless missing.empty?
-          end
-        end
-      end
-    end
-  end
-end

data/lib/paygate_pk/providers/pay_fast/tokenization/token.rb

@@ -1,65 +0,0 @@
-# frozen_string_literal: true
-
-require "bigdecimal"
-
-module PaygatePk
-  module Providers
-    module PayFast
-      module Tokenization
-        # used to generate the bearer_token
-        class Token < PaygatePk::Providers::PayFast::Client
-          TOKEN_ENDPOINT = "/api/token"
-          DEFAULT_GRANT_TYPE = "client_credentials"
-
-          # 3.1 Authentication Access Token
-          # Required: merchant_id, secured_key, grant_type
-          # Optional: customer_ip, reserved_1..3, api_version
-          # Returns: PaygatePk::Contracts::BearerToken
-          def get(grant_type: DEFAULT_GRANT_TYPE, options: {})
-            mid = config.merchant_id
-            sec = config.secured_key
-
-            ensure_present!(merchant_id: mid, secured_key: sec, grant_type: grant_type)
-
-            resp = http.post(TOKEN_ENDPOINT, form: body(mid, sec, grant_type, options))
-
-            PaygatePk::Contracts::BearerToken.new(
-              access_token: resp["token"], # if present
-              refresh_token: resp["refresh_token"], # shown in doc example
-              expiry: resp["expiry"],
-              code: resp["code"],
-              message: resp["message"],
-              raw: resp
-            )
-          end
-
-          private
-
-          def base_url
-            config.api_base_url
-          end
-
-          def body(mid, sec, grant_type, options)
-            attrs = {
-              "merchant_id" => mid,
-              "secured_key" => sec,
-              "grant_type" => grant_type
-            }
-            attrs["customer_ip"] = options[:customer_ip] if options[:customer_ip]
-            attrs["reserved_1"]  = options[:reserved1] if options[:reserved1]
-            attrs["reserved_2"] = options[:reserved2] if options[:reserved2]
-            attrs["reserved_3"]  = options[:reserved3] if options[:reserved3]
-            attrs["api_version"] = options[:api_version] if options[:api_version]
-
-            attrs
-          end
-
-          def ensure_present!(**pairs)
-            missing = pairs.select { |_k, v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }.keys
-            raise PaygatePk::ValidationError, "missing required args: #{missing.join(", ")}" unless missing.empty?
-          end
-        end
-      end
-    end
-  end
-end

data/lib/paygate_pk/providers/pay_fast/webhook.rb

@@ -1,74 +0,0 @@
-# frozen_string_literal: true
-
-module PaygatePk
-  module Providers
-    module PayFast
-      # Verifies PayFast IPN/notification params (GET to your CHECKOUT_URL)
-      # Returns PaygatePk::Contracts::WebhookEvent on success, raises on failure.
-      class Webhook
-        def verify!(raw_params)
-          params = normalize_keys(raw_params)
-
-          validate_required_params(params)
-          verify_signature(params)
-          build_webhook(params, raw_params)
-        end
-
-        private
-
-        def verify_signature(params)
-          expected = PaygatePk::Util::Signature::Payfast.validation_hash(
-            basket_id: params["basket_id"],
-            merchant_secret_key: PaygatePk.config.pay_fast.secured_key,
-            merchant_id: PaygatePk.config.pay_fast.merchant_id,
-            payfast_err_code: params["err_code"]
-          )
-          return if PaygatePk::Util::Security.secure_compare(expected, params["validation_hash"])
-
-          raise PaygatePk::SignatureError, "invalid validation_hash"
-        end
-
-        def validate_required_params(params)
-          %w[basket_id err_code validation_hash].each do |k|
-            raise PaygatePk::SignatureError, "missing #{k}" unless present?(params[k])
-          end
-        end
-
-        def normalize_keys(hash)
-          hash.transform_keys(&:to_s).tap do |x|
-            # common aliases to lowercase
-            x["instrument_token"] ||= x["Instrument_token"]
-            x["recurring_txn"]    ||= x["Recurring_txn"] || x["RECURRING_TXN"]
-          end
-        end
-
-        def present?(val)
-          !(val.nil? || (val.respond_to?(:empty?) && val.empty?))
-        end
-
-        def truthy?(val)
-          [true, "true", "TRUE", "1", 1].include?(val)
-        end
-
-        def build_webhook(params, raw_params)
-          PaygatePk::Contracts::WebhookEvent.new(
-            provider: :payfast,
-            transaction_id: params["transaction_id"],
-            basket_id: params["basket_id"],
-            order_date: params["order_date"],
-            approved: params["err_code"] == "000",
-            code: params["err_code"],
-            message: params["err_msg"],
-            amount: params["transaction_amount"],
-            merchant_amount: params["merchant_amount"],
-            payment_method: params["issuer_name"],
-            currency: params["currency"],
-            instrument_token: params["instrument_token"] || params["Instrument_token"],
-            recurring: truthy?(params["recurring_txn"]) || truthy?(params["RECURRING_TXN"]),
-            raw: raw_params
-          )
-        end
-      end
-    end
-  end
-end

data/lib/paygate_pk/util/html.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-require "nokogiri"
-
-module PaygatePk
-  module Util
-    # HTML parsing utilities
-    module Html
-      module_function
-
-      # Extract a specific <form> (default: first) into a hash of action/method/inputs
-      def extract_form(html, index: 0)
-        doc  = parse(html)
-        form = doc.css("form")[index]
-        return nil unless form
-
-        {
-          action: form["action"],
-          method: (form["method"] || "GET").upcase,
-          inputs: form.css("input[name]").to_h { |i| [i["name"], i["value"]] }
-        }
-      end
-
-      # NEW: Return the first anchor href (or nil) – handy for redirect pages
-      # Optionally pass a CSS selector (e.g., "a.pay-button") if you need a specific link.
-      def first_anchor_href(html, selector: "a")
-        doc = parse(html)
-        a   = doc.at(selector)
-        a ? a["href"] : nil
-      end
-
-      # --- internals ----------------------------------------------------------
-
-      def parse(html)
-        Nokogiri::HTML5(html)
-      rescue NoMethodError
-        # Fallback for environments without HTML5 parser
-        Nokogiri::HTML(html)
-      end
-    end
-  end
-end

data/lib/paygate_pk/util/signature.rb

@@ -1,18 +0,0 @@
-# lib/paygate_pk/util/signature.rb
-# frozen_string_literal: true
-
-require "openssl"
-
-module PaygatePk
-  module Util
-    module Signature
-      # validation_hash = SHA256("basket_id|merchant_secret_key|merchant_id|payfast_err_code")
-      module Payfast
-        def self.validation_hash(basket_id:, merchant_secret_key:, merchant_id:, payfast_err_code:)
-          data = [basket_id, merchant_secret_key, merchant_id, payfast_err_code].join("|")
-          OpenSSL::Digest::SHA256.hexdigest(data)
-        end
-      end
-    end
-  end
-end

data/paygate_pk.gemspec

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/paygate_pk/version"
-
-Gem::Specification.new do |spec|
-  spec.name       = "paygate_pk"
-  spec.version    = PaygatePk::VERSION
-  spec.authors    = ["Talha Junaid"]
-  spec.email      = ["talhajunaid65@gmail.com"]
-  spec.summary    = "Unified Ruby wrapper for PayFast"
-  spec.description = "Provider-agnostic Ruby/Rails client for PayFast: checkout, webhooks/IPN verification,
-                      tokenized & recurring payments."
-  spec.license     = "MIT"
-  spec.homepage    = "https://github.com/qbitechs/paygate_pk"
-  spec.metadata    = {
-    "source_code_uri" => "https://github.com/qbitechs/paygate_pk",
-    "changelog_uri" => "https://github.com/qbitechs/paygate_pk/blob/main/CHANGELOG.md",
-    "homepage_url" => spec.homepage
-  }
-
-  spec.required_ruby_version = ">= 2.6.0"
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor])
-    end
-  end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = %w[lib test]
-
-  # Runtime deps
-  spec.add_dependency "faraday", ">= 2.7"
-  spec.add_dependency "faraday-retry", ">= 2.0"
-  spec.add_dependency "json"
-  spec.add_dependency "nokogiri", ">= 1.16", "< 2.0"
-
-  spec.add_development_dependency "byebug"
-  spec.add_development_dependency "minitest", "~> 5.0"
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "rubocop", "~> 1.21"
-  spec.add_development_dependency "simplecov", ">= 0.22"
-  spec.add_development_dependency "webmock"
-end